The AI agent ecosystem has a packaging problem.
Frameworks for building agents have exploded. You can wire up a ReAct loop in a dozen languages, connect it to vector stores, give it tools, and watch it reason. The "how to build an agent" question is largely answered.
But ask a different question — how do you ship one? — and the answers get vague fast.
How do you hand an agent to another team and guarantee it behaves the same way? How do you version it, audit its permissions, constrain its filesystem access, and run it on a machine that has never seen your source code? How do you move it from a developer's laptop to a staging server to a CI pipeline without rewriting configuration at every step?
These are not agent intelligence problems. They are agent infrastructure problems. And they are exactly the problems that portable, bundle-first agent runtimes are built to solve.
The State of Agent Deployment Today
Most agent systems today are application-embedded. The agent's prompt, model configuration, tool definitions, memory strategy, and security policy live scattered across application code, environment variables, config files, and framework-specific abstractions. To "deploy" an agent means deploying the entire application that contains it.
This creates a set of familiar problems:
Environment coupling. The agent works on the author's machine because the right API keys are set, the right files are mounted, and the right tools are available. Move it somewhere else and things break silently — wrong model, missing tools, different filesystem layout.
No versioning boundary. When the agent's behavior changes, what changed? The prompt? The model? A tool implementation? A permission policy? Without a clear artifact boundary, there is no meaningful way to version, diff, or roll back an agent independently of the application around it.
Security as an afterthought. Tool permissions, filesystem access, and network policy are typically enforced (if at all) at the application layer. There is no standard way to declare that an agent should only read files in a workspace, or that Bash commands require human approval, or that outbound network access is restricted to specific hosts.
No portability. An agent built in one framework, with one team's conventions, cannot be handed to another team and run without understanding the full stack underneath it. There is no docker pull equivalent for agents.
These problems compound as organizations move from one experimental agent to dozens of production agents maintained by different teams. The lack of a standard packaging and execution model becomes a real operational bottleneck.
The Container Analogy
The container revolution solved an analogous problem for applications. Before Docker, deploying software meant managing dependencies, environment configuration, and runtime differences across machines. The container image became the unit of packaging — a portable, versioned artifact that could run anywhere a container runtime existed.
Agents need the same thing: a portable artifact that encapsulates identity, behavior, tools, permissions, and runtime policy in a single versioned unit.
This is the idea behind agent bundles.
What an Agent Bundle Looks Like
In Odyssey, the open-source Rust agent runtime built by LiquidOS, an agent bundle is a directory with a small, well-defined structure:
my-agent/
├── odyssey.bundle.json5 # Runtime policy
├── agent.yaml # Agent identity and behavior
├── skills/ # Reusable prompt extensions
│ └── code-review/
│ └── SKILL.md
└── resources/ # Bundle-local assets
└── reference.md
The bundle manifest (odyssey.bundle.json5) declares everything the runtime needs to execute the agent — no implicit dependencies, no environment assumptions:
{
id: 'code-reviewer',
version: '1.2.0',
manifest_version: "odyssey.bundle/v1",
agent_spec: 'agent.yaml',
// Execution strategy
executor: { type: 'prebuilt', id: 'react' },
memory: { type: 'prebuilt', id: 'sliding_window', config: { max_window: 100 } },
// Available tools
tools: [
{ name: 'Read', source: 'builtin' },
{ name: 'Glob', source: 'builtin' },
{ name: 'Grep', source: 'builtin' },
{ name: 'Bash', source: 'builtin' }
],
// Security boundary
sandbox: {
mode: 'read_only',
permissions: {
filesystem: {
mounts: { read: ["."], write: [] }
},
network: ["api.openai.com"]
},
resources: { cpu: 1, memory_mb: 512 }
}
}
The agent spec (agent.yaml) defines identity, prompt, model, and tool-level permissions:
id: code-reviewer
description: Reviews pull requests for correctness and style
prompt: |
You are a senior code reviewer. You read diffs carefully, check for
correctness, identify edge cases, and suggest improvements. You never
modify files directly — you only provide feedback.
model:
provider: openai
name: gpt-4.1-mini
tools:
allow: ['Read', 'Glob', 'Grep', 'Bash(git diff:*)', 'Bash(git log:*)']
ask: []
deny: ['Write', 'Edit', 'Bash']
Read that tools block carefully. This agent can read files and run git diff and git log, but it cannot write files, edit files, or run arbitrary shell commands. That policy is not enforced by convention or application-level checks — it is part of the bundle definition and enforced by the runtime. The sandbox mode is read_only, meaning even if a tool attempted a write, the kernel-level sandbox would block it.
This is what a portable, self-describing agent looks like.
The Lifecycle of a Portable Agent
Once an agent is defined as a bundle, its lifecycle becomes operationally clean:
Author
odyssey-rs init ./code-reviewer
# Edit the manifest, agent spec, and skills
Build and install
odyssey-rs build ./code-reviewer
The build step validates the manifest, resolves dependencies, and installs the bundle into the local bundle store (~/.odyssey/bundles/). The agent is now runnable by reference.
Run
odyssey-rs run code-reviewer@1.2.0 --prompt "Review the latest commit"
The runtime resolves the agent reference, loads the bundle, prepares the sandbox, assembles the execution context, and runs the agent loop. On a release build, this entire initialization — from CLI invocation to agent execution — takes under 200 microseconds.
Distribute
# Export to a portable archive
odyssey-rs export code-reviewer:1.2.0 --output ./dist
# On another machine — import and run
odyssey-rs import ./dist/code-reviewer-1.2.0.odyssey
odyssey-rs run code-reviewer@1.2.0 --prompt "Review this PR"
The .odyssey archive is a self-contained artifact. No source code, no framework installation, no environment setup beyond the Odyssey binary itself. The agent runs identically on any machine with odyssey-rs installed.
Serve remotely
# Start the runtime as an HTTP server
odyssey-rs serve --bind 0.0.0.0:8472
# Run agents remotely
odyssey-rs --remote http://server:8472 run code-reviewer@1.2.0 --prompt "Check main"
The same bundle, the same runtime contract, accessible over HTTP. No separate deployment pipeline.
Why Portability Changes the Game
When agents become portable artifacts, several things that were previously hard become straightforward:
Multi-agent teams without multi-repo chaos
A platform team can author, version, and distribute specialized agents — a code reviewer, a test writer, a documentation generator, an incident responder — as independent bundles. Product teams consume them by reference. Updating an agent means publishing a new version, not coordinating a cross-team deployment.
Auditable security posture
Every bundle explicitly declares what it can and cannot do. An agent with sandbox.mode: read_only and tools.deny: ['Bash'] has a security posture you can read in ten seconds. Compliance teams can review bundle manifests without reading source code. Permission changes are version-controlled diffs.
Reproducible behavior across environments
The same code-reviewer:1.2.0 bundle produces the same execution context on a developer laptop, in CI, and on a production server. The prompt, model, tools, memory strategy, and sandbox policy are fixed by the bundle version. Environment-specific differences (API keys) are injected at runtime, not baked into the artifact.
Agent-as-a-service without infrastructure overhead
The Odyssey HTTP server exposes the full runtime over REST. Any bundle installed on the server is immediately available as an API endpoint. There is no per-agent deployment, no container orchestration, no function-as-a-service wrapper. Install a bundle, and it is servable.
What This Means for the Industry
The shift toward portable, bundle-first agents is not just a developer experience improvement. It represents a fundamental change in how organizations will operate AI agents at scale:
Agents become auditable artifacts. When an agent's complete behavior is captured in a versioned bundle, security reviews, compliance audits, and incident investigations can work with concrete artifacts instead of reconstructing behavior from scattered code and configuration.
Agent distribution becomes a solved problem. The .odyssey archive format and the planned hub push/pull workflow mean agents can be published, discovered, and installed the same way packages and container images are today.
Runtime and agent become independent concerns. Teams that build agents do not need to understand or operate the runtime. Teams that operate the runtime do not need to understand agent internals. The bundle manifest is the contract between them.
Multi-provider, multi-surface deployment becomes trivial. The same bundle runs through CLI for scripting, HTTP for services, and TUI for interactive operation. Switching LLM providers is a configuration change, not an architectural decision.
Star the Repository - https://github.com/liquidos-ai/Odyssey if you like the project
Odyssey is built by LiquidOS. We believe the next generation of AI infrastructure will be defined by portable, auditable, and operationally practical agent runtimes — not larger frameworks.
Top comments (0)