You can either setup an
oxen-server instance yourself, or use the hosted version on OxenHub. To use the hosted OxenHub solution you can sign up here. The hosted solution comes with a UI and the benefits of not having to setup infrastructure yourself.
To setup a local Oxen Server instance, first install the
On Mac-OS you can use Homebrew to install the binary.
brew tap Oxen-AI/oxen-server
brew install oxen-server
To install on other platforms, follow the installation instructions.
The server can be run with access token authentication turned on or off. The server runs with no authentication by default:
To enable authentication, generate a token to give it to the user to access to the server
oxen-server add-user --email YOUR_EMAIL --name YOUR_NAME User access token created: XXXXXXXX To give user access have them run the command `oxen config --auth <HOST> <TOKEN>`
You may have different authentication tokens for different hosts. From the client side, you can setup an auth token per host with the
config command. If you ever need to debug or edit the tokens manually, they are stored in the
oxen config --auth <HOST> <TOKEN> cat ~/.oxen/user_config.toml
To run the server with authentication, use the
oxen-server start -a
The default directory that Oxen stores data is
/tmp/oxen_sync, we definitely do not want this in production. To change it set the SYNC_DIR environment variable to a path.
$ export SYNC_DIR=/Path/To/Data oxen-server start -a Running 🐂 server on 0.0.0.0:3000 Syncing to directory: /Path/To/Data [2022-06-08T10:00:48Z INFO actix_server::builder] Starting 8 workers [2022-06-08T10:00:48Z INFO actix_server::server] Actix runtime found; starting in Actix runtime
If you want to change the default
IP ADDRESS and
PORT you can do so by passing them in with the
oxen-server start -i 0.0.0.0 -p 4321
Pushing the Changes
Once you have committed data locally and are ready to share them with colleagues (or the world) you will have to push them to a remote.
You can either create a remote through the web UI on OxenHub or if you have setup a server your self, you will have to run the
oxen create-remote MyNamespace MyRepoName <HOST>
Repositories that live on an Oxen Server have the idea of a
namespace and a
name to help you organize your repositories.
Once you know your remote repository URL you can add it as a remote.
oxen config --set-remote origin http://<HOST>/MyNamespace/MyRepoName
Once a remote is set you can push
oxen push origin main
You can change the remote (origin) and the branch (main) to whichever remote and branch you want to push.
Clone the Changes
To clone a repository from remote server you can use the URL you provided previously, and pull the changes to a new machine.
oxen clone http://<HOST>/MyNamespace/MyRepoName
Note: Due to the potential size of data, you can supply the
--shallow flag so that oxen does not immediately pull all the data. You can then navigate into the directory, and pull the specific branch that you want.
oxen clone http://<HOST>/MyNamespace/MyRepoName --shallow $ cd MyRepoName oxen pull origin main