Odyssey

Define, build, and run agents as portable bundles.

Open-source Rust runtime for packaging, securing, and operating portable AI agents.

Documentation | Contributing

Like this project? Star us on GitHub

---

Status: Odyssey is under active development and should be treated as pre-production software.

Odyssey is an open-source, bundle-first agent runtime written in Rust on top of AutoAgents - Agent Framework in Rust. It lets you define an agent once, package it as a portable artifact, and run it through the same execution model across local development, embedded SDK usage, shared runtime servers, and terminal workflows.

The project is built around a simple idea:

• author agents as portable bundles
• run them with built-in sandboxing and approvals
• ship with prebuilt tools, executors, and memory providers
• expose the same runtime through CLI, HTTP, and TUI surfaces
• grow toward custom executors, memory providers, tools, and WASM-based extensions

Odyssey currently uses prebuilt executors and prebuilt memory providers in v1. Custom extensions and WASM support are planned.

Why Odyssey

• Bundle-first delivery: agents are packaged artifacts, not scattered app-local configuration.
• One runtime, many surfaces: the SDK, CLI, HTTP server, and TUI all sit on the same runtime contract.
• Security by default: sandbox mode, tool approvals, filesystem mounts, and network rules are part of the bundle definition.
• Operationally practical: local install, export/import, and hub push/pull workflows are built in.
• Rust-native core: explicit types, embeddable crates, and a runtime that can be used directly in applications.

What You Get Today

• Embeddable runtime via OdysseyRuntime
• Bundle manifests and validation
• Local bundle build and install flow
• Portable .odyssey export/import
• Built-in tools and policy-controlled approvals
• Sandboxed execution with filesystem and network controls
• CLI for authoring and operations
• HTTP server for remote runtime access
• TUI for local operator workflows

Roadmap

• Hub push/pull distribution flow
• Custom executors
• Custom memory providers
• Native macOS and Windows sandbox providers
• Custom tools
• WASM-based extension support
• Stronger pluggability around runtime components

Core Concepts

Bundles

An Odyssey bundle is the unit of portability. A typical bundle contains:

• odyssey.bundle.json5 for runtime policy, tools, sandbox, executor, and memory configuration
• agent.yaml for agent identity, prompt, model, and tool policy
• skills/ for reusable prompt extensions
• resources/ for bundle-local assets

Runtime

At execution time, Odyssey resolves an AgentRef to an installed bundle, creates a session, prepares an isolated workspace, loads skills and tools, applies sandbox policy, attaches memory, and executes the turn through the configured runtime pipeline.

Interfaces

The same runtime is available through:

• odyssey-rs for CLI workflows
• odyssey-rs tui for terminal-native operation
• odyssey-rs serve for HTTP access

Installation

Install the Odyssey 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 the odyssey-rs binary into ~/.local/bin by default.

If you prefer the direct crates.io path, install it with Cargo:

cargo install odyssey-rs

This installs the odyssey-rs binary.

If you are working from a source checkout instead, replace odyssey-rs in the examples below with:

cargo run -p odyssey-rs --

Quickstart

1. Initialize a bundle

odyssey-rs init ./hello-world

This creates a starter project with:

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

The starter template currently uses the react executor, sliding_window memory, all builtin tools, and a development-friendly sandbox policy. Tighten the bundle manifest before production use.

2. Build and install locally

odyssey-rs build ./hello-world

Build to a custom output directory instead:

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

3. Run an agent

export OPENAI_API_KEY="your-key"
odyssey-rs run hello-world@latest --prompt "Hey, What are your capabilities?"

Run the agent in the TUI. The TUI automatically loads installed bundles and handles tools with ASK policy through the same odyssey-rs CLI entrypoint.

export OPENAI_API_KEY="your-key"
odyssey-rs tui --bundle hello-world@latest

4. Inspect installed metadata

odyssey-rs inspect hello-world@latest

5. Start the runtime server

odyssey-rs serve --bind 127.0.0.1:8472

You can then target that runtime remotely:

odyssey-rs --remote http://127.0.0.1:8472 bundles
odyssey-rs --remote http://127.0.0.1:8472 inspect hello-world@latest
odyssey-rs --remote http://127.0.0.1:8472 run hello-world@latest --prompt "Summarize this bundle"
odyssey-rs --remote http://127.0.0.1:8472 sessions

Docker on macOS

Odyssey's confined sandbox backend is Linux-only today. On macOS and Windows, read_only and workspace_write bundle sandboxes require a Linux environment. If you want the current bubblewrap-based sandbox on macOS, use the included Docker image. If you only need local host execution, use --dangerous-sandbox-mode instead.

Build the image:

docker compose build odyssey

Start an interactive shell in the Linux container:

docker compose run --rm odyssey

Inside the container, the image gives you the source checkout instead of a preinstalled odyssey-rs binary, so run the CLI from source:

export OPENAI_API_KEY="your-key"
cargo run -p odyssey-rs --release -- build ./bundles/hello-world
cargo run -p odyssey-rs --release -- run hello-world@latest --prompt "What can you do?"

The Compose setup mounts this repository at /workspace. Odyssey creates and uses /home/odyssey/.odyssey inside the container itself, so it stays isolated from the host filesystem.

To expose the runtime server back to the host, publish ports and bind to 0.0.0.0:

docker compose run --rm --service-ports odyssey \
  cargo run -p odyssey-rs --release -- serve --bind 0.0.0.0:8472

Then connect from the host with:

odyssey-rs --remote http://127.0.0.1:8472 bundles

If you only need host execution and do not need the Linux sandbox backend, native macOS runs are still possible with --dangerous-sandbox-mode.

Bundle Distribution

Export a portable archive:

odyssey-rs export local/hello-world:0.1.0 --output ./dist

Import a portable archive:

odyssey-rs import ./dist/hello-world-0.1.0.odyssey

Security Model

Odyssey treats execution policy as part of the runtime contract.

• Bundles declare a sandbox mode such as read_only or workspace_write.
• Tool actions can be set to allow, deny, or ask.
• Tool permissions can be coarse (Bash) or granular (Bash(cargo test:*)).
• Filesystem access is controlled through explicit host mounts.
• Outbound network access is controlled through sandbox policy.
• Approval flows suspend the active turn and resume it after resolution.

For local debugging, the CLI and server support --dangerous-sandbox-mode, which bypasses sandbox restrictions and runs with host access. Use it sparingly.

Repository Layout

• crates/odyssey-rs: CLI entrypoint and facade crate, including the tui command
• crates/odyssey-rs-manifest: bundle manifest parsing and validation
• crates/odyssey-rs-bundle: build, install, inspect, export, import, push, and pull
• crates/odyssey-rs-protocol: shared runtime protocol types
• crates/odyssey-rs-runtime: core runtime, sessions, execution, tools, memory, and sandbox integration
• crates/odyssey-rs-tools: built-in tools and tool adaptors
• crates/odyssey-rs-sandbox: sandbox runtime and providers
• crates/odyssey-rs-server: Axum-based HTTP API
• crates/odyssey-rs-tui: Ratatui-based terminal UI implementation used by odyssey-rs tui
• bundles/hello-world: minimal example bundle
• bundles/odyssey-agent: Odyssey general purpose agent

Development

Prerequisites

• Rust toolchain
• rg
• tokei
• Docker Desktop or another recent Docker engine when running the Linux sandbox workflow on macOS

Quality Gates

cargo fmt --all
cargo clippy --workspace --all-targets -- -D warnings
cargo test --all-features

Coverage

cargo tarpaulin --engine llvm --skip-clean --workspace --all-features --timeout 120 --out Xml --ignore-panics

Documentation

• Documentation site

Contributing

Contributions are welcome. See CONTRIBUTING.md for development workflow, quality expectations, and pull request guidance.

Community

• GitHub Issues: Bug reports and feature requests
• Discussions: Community Q&A and ideas
• Discord: Join our Discord Community using https://discord.gg/zfAF9MkEtK

License

Odyssey is licensed under Apache 2.0. See APACHE_LICENSE.