Odyssey Documentation

Odyssey packages an AI agent as a portable bundle, then runs that bundle through the same runtime contract across the CLI, TUI, HTTP server, and embedded Rust usage. The bundle defines the agent, the sandbox policy, the available tools, and the runtime defaults; the runtime turns that bundle into sessions, turns, events, approvals, and persisted history.

Install The CLI

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

Start Here

• Getting Started for the first local bundle workflow
• CLI and Server for commands, bundle references, and HTTP routes
• Bundle Format for odyssey.bundle.yaml, per-agent agent.yaml, and build layout
• Sandbox and Tools for confinement, mounts, exec policy, and approvals
• Runtime Model for the public runtime API and execution lifecycle
• Events and Approvals for session event streaming and approval flow
• Runtime Architecture for the internal system design

Mental Model

Concept	What it means
Bundle	The installable unit. It contains the manifest, the agent spec, skills, resources, and runtime policy.
Session	A persisted conversation bound to one bundle and one chosen model configuration.
Turn	One submitted task plus its streamed events and stored result.
Sandbox cell	A reusable per-session workspace prepared for bundle tools and direct commands.
Runtime	The process-wide engine that owns the bundle store, session store, sandboxes, scheduler, tools, and approvals.

Choose An Interface

Surface	Best for	Notes
odyssey-rs run	One-shot prompts	Creates a fresh session, runs one turn, prints the final response.
odyssey-rs tui	Local operator workflows	Uses the same local runtime and supports tool approvals and session selection.
odyssey-rs serve	Shared runtime access	Exposes bundle and session APIs over HTTP plus SSE event streaming.
OdysseyRuntime	Embedded Rust apps	Gives direct access to bundle, session, execution, and approval APIs.

Current Capabilities

• Bundle authoring, install, export, import, publish, and pull flows are built in.
• The runtime persists sessions to disk and streams execution events in real time.
• Builtin tools cover file access, search, edits, shell commands, and bundle skill lookup.
• The only executor currently implemented is react.
• The only memory provider currently implemented is session-window/v1.
• Manifest tool entries currently support builtin tools only.
• Cloud model providers currently wired into the runtime are Anthropic, Azure OpenAI, DeepSeek, Google or Gemini, Groq, MiniMax, OpenAI, OpenRouter, Phind, and xAI.
• Local Hugging Face-backed llama.cpp models are also supported through the llama_cpp provider.

Platform Notes

• Restricted sandboxes are currently Linux-only and use bubblewrap.
• On macOS and Windows, local execution currently requires --dangerous-sandbox-mode or a Linux container if you want confined execution.

Workspace Crates

Crate	Purpose
odyssey-rs-manifest	Parses and validates bundle manifests and agent specs
odyssey-rs-bundle	Builds, installs, exports, imports, publishes, and pulls bundles
odyssey-rs-runtime	Owns sessions, sandbox preparation, prompt assembly, tool routing, approvals, and execution
odyssey-rs-tools	Provides the builtin tool set
odyssey-rs-sandbox	Provides host and Linux sandbox backends
odyssey-rs-server	HTTP surface over the runtime
odyssey-rs	CLI facade, including the tui command
odyssey-rs-tui	Terminal UI crate used by odyssey-rs tui

API Reference

• docs.rs for crate-level Rust API docs