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.

​
Install

To setup a local Oxen Server instance, first install the oxen-server binary.

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.

​
Run

The server can be run with access token authentication turned on or off. The server runs with no authentication by default:

oxen-server start

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/user_config.toml file.

oxen config --auth <HOST> <TOKEN>
cat ~/.oxen/user_config.toml

To run the server with authentication, use the -a flag

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 -i and -p parameters.

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 create-remote command.

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
🌎 Oxen HubData Frames