Documentation

Everything you need to install Octo, create your first project, and run code locally or remotely.

Requirements

Docker must be installed and running on your server/workstation.
Ensure your client PC can reach the server IP and port (default 5000).
Server user must have permission to use Docker (usually in the docker group).

System Overview

                ┌──────────────────┐
                │       PC         │
                │                  │
                │   Octo-Client    │
                │   (Submit Jobs)  │
                └─────────┬────────┘
                          │
                          ▼
┌────────────────────────────────────────────────────────┐
│                   PC / Server                          │
│                                                        │
│   ┌──────────────────────────────────────────────┐     │
│   │               Octo-Server                    │     │
│   │                 (Queue)                      │     │
│   └──────────────────────┬───────────────────────┘     │
│                          │                             │
│        ┌─────────────────┼─────────────────┐           │
│        ▼                 ▼                 ▼           │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ Octo-Runner  │  │ Octo-Runner  │  │ Octo-Runner  │  │
│  │     #1       │  │     #2       │  │     #3       │  │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘  │
│         ▼                 ▼                 ▼          │
│     Docker             Docker             Docker       │ 
│  Isolated Run       Isolated Run       Isolated Run    │
│                                                        │
│        ⋯  one or more runners are possible  ⋯          │
└────────────────────────────────────────────────────────┘

Quickstart

Install
Install Octo-Server and Octo-Runner on your server/workstation, and Octo-Client on your PC.

Tip: Use octo --help, octo-server --help or octo-runner --help to check installation.
Start Server and Runner
On your server open two terminal windows:

Terminal Window 1 — Add a token

octo-server token-add token123

Start Server

octo-server server

Terminal Window 2 — Start Runner

octo-runner --token token123
Connect Client
On your PC, login with:

octo login --token token123 --server http://192.168.0.172:5000

Run your code with octo:

octo run main.py

CLI Commands

Client

Command	Description
`octo login --token token123 --server http://ip:port`	Login to server
`octo run main.py`	Run entry file in project folder
`octo config --help`	Show config help
`octo config --docker python:3.11`	Set Docker image
`octo config --install`	Install requirements.txt
`octo config --noinstall`	Skip requirements.txt installation
`octo config --gpu all`	Set GPU usage (e.g. none, all, 0, 0,1)
`octo config --ram 8g`	Set RAM limit
`octo config --cpu 2`	Set CPU limit
`octo config --shm-size 1g`	Set shared memory size

Server

Command	Description
`octo-server server`	Start server
`octo-server token-list`	List tokens
`octo-server token-add demo-token`	Add a new token
`octo-server token-remove demo-token`	Remove a token
`octo-server server --host 0.0.0.0 --port 5001`	Start server with custom host and port

Runner

Command	Description
`octo-runner --token demo`	Start runner with token
`octo-runner --token demo --server http://ip:5001`	Start runner with custom server host

Example: Running Octo on a Remote Workstation

Here is a showcase on how to use Octo in your project:

Let’s say you have a high-end workstation and want to run code there because execution is faster or you have better GPUs.

1) Server side

SSH into your server:

ssh user@ip

Check existing tokens:

octo-server token-list

Add a new token:

octo-server token-add demo-token

Start the runner in a second terminal window:

octo-runner --token demo-token

2) Client side

On your PC go to your project folder:

cd demo_project

octo login --token demo-token --server http://192.168.0.172:5000

Configure resource limits:

octo config --docker python:3.11 --noinstall --gpu all --cpu 2 --ram 8

Run your code:

octo run main.py

Troubleshooting

Check installation and tokens if runners don’t connect.

If your Client cannot connect to the Server make sure that the Firewall settings are not blocking the communication. Also make sure that the User on the Server has permission to use Docker (e.g. is in the docker group).
Additional tip: Verify the token you are using matches between Client and Runner. Ensure network ports are accessible, and Docker daemon is running correctly.