openai-agents-maritime
Give every OpenAI Agents SDK sandbox agent its own cloud computer on Maritime.
A real Linux machine per run: the agent's shell, files and patches run there, never on your laptop or server.
Quickstart · Options · Resume · What is supported · More agents on Maritime
Quickstart
pip install openai-agents-maritime
export MARITIME_API_KEY=mk_... # maritime.sh/settings/api-keys
export OPENAI_API_KEY=sk-...
import asyncio
from agents import RunConfig, Runner
from agents.sandbox import SandboxAgent, SandboxRunConfig
from agents.sandbox.capabilities import Filesystem, Shell
from openai_agents_maritime import MaritimeSandboxClient, MaritimeSandboxClientOptions
agent = SandboxAgent(
name="Coder",
model="gpt-5.4",
instructions="You work inside a Linux sandbox. Use the shell and files to do the task.",
capabilities=[Shell(), Filesystem()],
)
async def main() -> None:
result = await Runner.run(
agent,
"Write fizzbuzz.py for 1 to 15, run it, and tell me the last three lines.",
run_config=RunConfig(
sandbox=SandboxRunConfig(
client=MaritimeSandboxClient(),
options=MaritimeSandboxClientOptions(),
)
),
)
print(result.final_output)
asyncio.run(main())
When the run starts, Maritime boots a fresh sandbox in a few seconds. The agent writes and runs code there, and the sandbox ends when the run ends.
Two runnable examples are in examples/:
scripted_demo.pyruns a real sandbox with the SDK'sScriptedModel, so it needs onlyMARITIME_API_KEY.llm_agent.pyis the coding agent above.
No OpenAI account? Maritime LLM is OpenAI-compatible: set OPENAI_BASE_URL=https://api.maritime.sh/api/llm/v1 and use your Maritime LLM token as OPENAI_API_KEY.
What the agent gets
- Its own Linux machine. Ubuntu 24.04 with Python 3.12, Node, git and curl, 2 vCPUs, 4 GiB of memory and 12 GiB of disk by default, up to 16 vCPUs and 64 GiB.
- Real isolation. Each sandbox is a microVM with its own kernel, filesystem, network and processes.
- Root when it needs it. Commands run as
user, with passwordlesssudofor installs. - Your files on arrival. Manifest
FileandDirentries are written into the workspace before the first turn. - Private web previews. A port in
exposed_portsgets an HTTPS URL that carries an access token, so a dev server the agent starts is reachable by you and nobody else. - Limits that clean up after you. An idle timeout pauses or ends a forgotten sandbox, and
time_limit_secondsends it no matter what.
Options
MaritimeSandboxClientOptions rejects unknown fields, so a typo never silently drops a setting.
| Option | Default | What it does |
|---|---|---|
template |
base |
A saved snapshot, a template, or a public image to start from. |
size |
small |
A preset: small, medium, large or xlarge. |
vcpu, memory_mib, disk_gib |
from size |
Override the preset: 1 to 16 vCPUs, 1,024 to 65,536 MiB, 5 to 500 GiB. |
env |
{} |
Environment variables for every command. |
metadata |
{} |
Labels you can filter on when you list sandboxes. |
name |
none | A unique name. Creating a name that already runs returns that sandbox. |
end_user |
none | Your id for the person this sandbox works for. |
idle_timeout_seconds |
600 |
How long without activity before on_idle applies. |
on_idle |
pause |
pause keeps the disk and resumes on the next call. kill ends the sandbox. |
time_limit_seconds |
none | End the sandbox this long after it starts, from 60 to 86,400. |
pause_on_exit |
False |
Pause instead of ending the sandbox when the run's session closes. |
exposed_ports |
() |
Ports the agent may expose over HTTPS. |
exec_timeout_unbounded_s |
3600 |
The timeout for commands the SDK runs without one. |
The workspace is /home/user/workspace unless your manifest sets root. A root outside the home directory, such as the SDK's default /workspace, is created with sudo and handed to user.
Keep a sandbox between runs
With pause_on_exit=True the sandbox pauses when the run ends instead of ending. Save the run state, and the next run reconnects to the same machine with everything the agent installed still there. If the sandbox has ended since, a new one is created with the same settings and the SDK restores the workspace from its snapshot.
options = MaritimeSandboxClientOptions(pause_on_exit=True, idle_timeout_seconds=1800)
You can also own the session yourself and use it across several runs:
client = MaritimeSandboxClient()
session = await client.create(options=MaritimeSandboxClientOptions())
run_config = RunConfig(sandbox=SandboxRunConfig(session=session))
async with session:
await Runner.run(agent, "Clone the repo and install it.", run_config=run_config)
await Runner.run(agent, "Now run the tests.", run_config=run_config)
await client.delete(session)
For anything this adapter does not wrap, session._inner.sandbox is the Maritime Python SDK Sandbox.
What is supported
| Feature | Status |
|---|---|
Shell, Filesystem and apply_patch tools |
Supported |
Manifest File and Dir entries, environment |
Supported |
| Workspace snapshots and resume | Supported |
| Pause on exit, reconnect on resume | Supported |
| Exposed ports | Supported, private HTTPS URL with a token |
| Running commands as another user | Supported, through sudo -u |
Interactive PTY sessions (write_stdin) |
Not yet: commands run to completion |
| Manifest mounts (S3, GCS, R2, Azure) | Not yet: rejected before a sandbox is created |
env is saved in the run state so an ended sandbox can be recreated with the same settings. Keep secrets you would not store with your run state out of it.
Compatibility
| Package | Versions |
|---|---|
| Python | 3.10 to 3.13 |
openai-agents |
0.24.x and 0.25.x |
maritime |
0.11.x and 0.12.x |
The SDK's sandbox interfaces are new and change between minor versions, so this package pins the range it is tested on.
Develop
uv sync --group dev
uv run pytest # unit tests, no account needed
MARITIME_API_KEY=mk_... uv run pytest -m live # real sandboxes on your account
The unit tests swap only the network calls: commands really run and files really move, so the SDK's path checks, tar snapshots and patching are exercised for real. The live tests create real sandboxes, check commands, files, timeouts, snapshots, an HTTPS port, pause and resume, and confirm every sandbox ends.
License
Metadata
Release files for openai-agents-maritime 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openai_agents_maritime-0.1.0.tar.gz | 19.0 kB | Without provenance | Details for openai_agents_maritime-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openai_agents_maritime-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for openai_agents_maritime-0.1.0-py3-none-any.whl |
Total release size: 31.5 kB
Release files / openai_agents_maritime-0.1.0.tar.gz
| Download URL | openai_agents_maritime-0.1.0.tar.gz |
|---|---|
| Size | 19.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dac9feca1061aee8323a0d7728855298ff0330bea9e8a42e6c7a9f47e1e17b55
|
|
BLAKE2b-256 checksum How to use checksums |
fcdac4120272b8940dc6e050f1c70887146d6cc701c23e79c3e1abf1a2cfd90d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.11
|
Release files / openai_agents_maritime-0.1.0-py3-none-any.whl
| Download URL | openai_agents_maritime-0.1.0-py3-none-any.whl |
|---|---|
| Size | 12.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
18c12b5437c1bafefadeb262fad3c25d9f4c52a833484d84223dc8bb26532176
|
|
BLAKE2b-256 checksum How to use checksums |
db0921a05fbb932db36d41b97351bce87ead1c313b39b4312c671ae15e37bb35
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.11
|
Security for openai-agents-maritime 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.