Skip to main content

Getting Started

Prerequisites​

  • A Rust toolchain
  • An API key for the cloud model provider your bundle uses
  • On Linux, bubblewrap (bwrap) in PATH if you want restricted sandbox execution

If you are developing on macOS or Windows, confined bundle sandboxes are not available yet. Use --dangerous-sandbox-mode for local development or run Odyssey inside a Linux container.

Install Odyssey​

Install the CLI with the bootstrap script:

curl -fsSL https://raw.githubusercontent.com/liquidos-ai/odyssey/main/install.sh | bash

The installer downloads the prebuilt release archive for the current platform and installs odyssey-rs into ~/.local/bin by default. You can also install it directly with Cargo:

cargo install odyssey-rs
odyssey-rs --help

Initialize A Bundle​

Create a starter bundle project:

odyssey-rs init ./hello-world

The template creates a small bundle project:

  • odyssey.bundle.json5
  • agent.yaml
  • README.md
  • skills/
  • resources/

The starter template is intentionally usable out of the box. It currently:

  • uses the react executor
  • uses the sliding_window memory provider
  • sets the default model in agent.yaml to openai / gpt-4.1-mini
  • lists all builtin tools explicitly in manifest.tools
  • starts with sandbox.mode: "read_only"
  • enables bundle-command network access with sandbox.permissions.network: ["*"]
  • uses sandbox.system_tools_mode: "standard"

That is a convenient development starting point, not a production-hardening template. Tighten the bundle policy before you treat a bundle as trusted automation.

Build And Install​

Build a project and install it into the local bundle store:

odyssey-rs build ./hello-world

Without --output, the CLI installs into the runtime cache under:

~/.odyssey/bundles/installs/local/<bundle-id>/<version>

Build an OCI-style bundle layout into a custom output directory instead:

odyssey-rs build ./hello-world --output ./dist

Bundle references accept a few useful forms:

  • hello-world or hello-world@latest for the latest installed local bundle
  • local/hello-world:0.1.0 for an explicit namespace and version
  • ./dist for a built bundle layout directory

Run A Prompt​

run is a one-shot command. It creates a fresh session, sends one prompt, prints the final assistant response, and exits.

export OPENAI_API_KEY="your-key"
odyssey-rs run hello-world@latest --prompt "What can you do?"

On macOS, Windows, or whenever you intentionally want host execution for local debugging:

odyssey-rs run hello-world@latest --prompt "What can you do?" --dangerous-sandbox-mode

Inspect And List​

Inspect installed bundle metadata:

odyssey-rs inspect hello-world@latest

List installed bundles and persisted sessions:

odyssey-rs bundles
odyssey-rs sessions

Use The TUI​

The TUI uses the same local runtime as the CLI:

odyssey-rs tui --bundle hello-world@latest

Inside the TUI:

  • plain text submits a normal chat turn
  • slash commands manage bundle and session workflow
  • lines starting with ! run a direct operator command inside the current session sandbox, such as !ls -la

Direct operator commands are not stored as normal session turns. They are an operator workflow for inspection and debugging.

Start The HTTP Runtime​

Run the Axum server on the default bind address:

odyssey-rs serve

Or choose a custom bind address:

odyssey-rs serve --bind 127.0.0.1:8472

The HTTP server wraps the same runtime type that the CLI and TUI use locally.

Create a session over HTTP:

curl -s -X POST http://127.0.0.1:8472/sessions \
  -H 'content-type: application/json' \
  -d '{"bundle_ref":"hello-world@latest"}'

Run a turn synchronously against an existing session:

curl -s -X POST http://127.0.0.1:8472/sessions/<session-id>/run-sync \
  -H 'content-type: application/json' \
  -d '{
    "input": {
      "prompt": "Summarize yourself in one paragraph",
      "submission_id": "11111111-1111-1111-1111-111111111111",
      "completed": false
    }
  }'

The server accepts the protocol Task shape in input. The CLI and TUI build that structure for you, so you only need to care about it when calling HTTP directly.

The CLI can also target a running server with --remote for the commands that support remote execution:

odyssey-rs --remote http://127.0.0.1:8472 bundles
odyssey-rs --remote http://127.0.0.1:8472 run hello-world@latest --prompt "Summarize yourself"