langchain-maritime 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- langchain_maritime-0.1.0/.gitignore +11 -0
- langchain_maritime-0.1.0/LICENSE +21 -0
- langchain_maritime-0.1.0/PKG-INFO +186 -0
- langchain_maritime-0.1.0/README.md +160 -0
- langchain_maritime-0.1.0/examples/deep_agent.py +43 -0
- langchain_maritime-0.1.0/langchain_maritime/__init__.py +6 -0
- langchain_maritime-0.1.0/langchain_maritime/_version.py +1 -0
- langchain_maritime-0.1.0/langchain_maritime/dcode.py +152 -0
- langchain_maritime-0.1.0/langchain_maritime/py.typed +0 -0
- langchain_maritime-0.1.0/langchain_maritime/sandbox.py +199 -0
- langchain_maritime-0.1.0/pyproject.toml +73 -0
- langchain_maritime-0.1.0/tests/__init__.py +0 -0
- langchain_maritime-0.1.0/tests/integration_tests/__init__.py +0 -0
- langchain_maritime-0.1.0/tests/integration_tests/conftest.py +42 -0
- langchain_maritime-0.1.0/tests/integration_tests/test_dcode_live.py +52 -0
- langchain_maritime-0.1.0/tests/integration_tests/test_standard.py +32 -0
- langchain_maritime-0.1.0/tests/unit_tests/__init__.py +0 -0
- langchain_maritime-0.1.0/tests/unit_tests/fakes.py +120 -0
- langchain_maritime-0.1.0/tests/unit_tests/test_dcode.py +136 -0
- langchain_maritime-0.1.0/tests/unit_tests/test_sandbox.py +173 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Maritime
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: langchain-maritime
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Maritime sandboxes for Deep Agents: run every tool on a real cloud computer.
|
|
5
|
+
Project-URL: Homepage, https://maritime.sh
|
|
6
|
+
Project-URL: Documentation, https://maritime.sh/docs
|
|
7
|
+
Project-URL: Repository, https://github.com/maritime-sh/langchain-maritime
|
|
8
|
+
Project-URL: Issues, https://github.com/maritime-sh/langchain-maritime/issues
|
|
9
|
+
Author-email: Maritime <contact@maritime.sh>
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: ai agents,cloud computer,deep agents,deepagents,langchain,maritime,sandbox
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Intended Audience :: Developers
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
21
|
+
Classifier: Typing :: Typed
|
|
22
|
+
Requires-Python: <4.0,>=3.11
|
|
23
|
+
Requires-Dist: deepagents<0.8.0,>=0.7.34
|
|
24
|
+
Requires-Dist: maritime<0.13.0,>=0.11.0
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
<p align="center">
|
|
28
|
+
<a href="https://maritime.sh">
|
|
29
|
+
<picture>
|
|
30
|
+
<source media="(prefers-color-scheme: dark)" srcset="assets/maritime-mark-white.png">
|
|
31
|
+
<img src="assets/maritime-mark-black.png" width="64" alt="Maritime">
|
|
32
|
+
</picture>
|
|
33
|
+
</a>
|
|
34
|
+
</p>
|
|
35
|
+
|
|
36
|
+
<h1 align="center">langchain-maritime</h1>
|
|
37
|
+
|
|
38
|
+
<p align="center"><a href="https://pypi.org/project/langchain-maritime/"><img src="https://img.shields.io/pypi/v/langchain-maritime?style=flat-square&color=2563eb" alt="PyPI"></a> <a href="https://pypi.org/project/langchain-maritime/"><img src="https://img.shields.io/pypi/pyversions/langchain-maritime?style=flat-square" alt="Python versions"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0a0a0a?style=flat-square" alt="MIT license"></a> <a href="https://github.com/maritime-sh/langchain-maritime/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/maritime-sh/langchain-maritime/test.yml?branch=main&style=flat-square&label=tests" alt="Tests"></a> <a href="https://maritime.sh/docs"><img src="https://img.shields.io/badge/docs-maritime.sh-0a0a0a?style=flat-square" alt="Docs"></a> <a href="https://discord.gg/wvPAvXNZqm"><img src="https://img.shields.io/badge/Discord-join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a></p>
|
|
39
|
+
|
|
40
|
+
<p align="center">
|
|
41
|
+
<b>Run <a href="https://github.com/langchain-ai/deepagents">Deep Agents</a> on a real cloud computer from <a href="https://maritime.sh">Maritime</a>.</b><br>
|
|
42
|
+
Every file read, edit, search and shell command happens in the agent's own Linux sandbox, never on your machine.
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
<p align="center">
|
|
46
|
+
<a href="#quickstart">Quickstart</a> ·
|
|
47
|
+
<a href="#deep-agents-code">Deep Agents Code</a> ·
|
|
48
|
+
<a href="#options">Options</a> ·
|
|
49
|
+
<a href="#tested">Tested</a> ·
|
|
50
|
+
<a href="https://github.com/maritime-sh/agents">More agents on Maritime</a>
|
|
51
|
+
</p>
|
|
52
|
+
|
|
53
|
+
## Quickstart
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pip install langchain-maritime langchain-openai
|
|
57
|
+
export MARITIME_API_KEY=mk_... # maritime.sh/settings/api-keys
|
|
58
|
+
export OPENAI_API_KEY=sk-...
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
```python
|
|
62
|
+
from deepagents import create_deep_agent
|
|
63
|
+
from langchain_openai import ChatOpenAI
|
|
64
|
+
|
|
65
|
+
from langchain_maritime import MaritimeSandbox
|
|
66
|
+
|
|
67
|
+
backend = MaritimeSandbox.create(idle_timeout_seconds=600)
|
|
68
|
+
try:
|
|
69
|
+
agent = create_deep_agent(model=ChatOpenAI(model="gpt-5.4"), backend=backend)
|
|
70
|
+
result = agent.invoke(
|
|
71
|
+
{
|
|
72
|
+
"messages": [
|
|
73
|
+
{
|
|
74
|
+
"role": "user",
|
|
75
|
+
"content": "Write primes.py that prints 10 primes, run it, show me the output.",
|
|
76
|
+
}
|
|
77
|
+
]
|
|
78
|
+
}
|
|
79
|
+
)
|
|
80
|
+
print(result["messages"][-1].content)
|
|
81
|
+
finally:
|
|
82
|
+
backend.kill()
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
`MaritimeSandbox.create()` starts a fresh sandbox in a few seconds. The agent's `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` and `execute` tools all run inside it.
|
|
86
|
+
|
|
87
|
+
Already have a sandbox? Wrap it:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from maritime import Maritime
|
|
91
|
+
|
|
92
|
+
sandbox = Maritime().sandboxes.get("sbx-...")
|
|
93
|
+
backend = MaritimeSandbox(sandbox=sandbox)
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The runnable version is [`examples/deep_agent.py`](examples/deep_agent.py). No OpenAI account? [Maritime LLM](https://maritime.sh/docs/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`.
|
|
97
|
+
|
|
98
|
+
## Deep Agents Code
|
|
99
|
+
|
|
100
|
+
Installing this package adds a `maritime` sandbox to [Deep Agents Code](https://github.com/langchain-ai/deepagents/tree/main/libs/code). No config needed:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
dcode install langchain-maritime --package
|
|
104
|
+
export MARITIME_API_KEY=mk_...
|
|
105
|
+
dcode --sandbox maritime
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Deep Agents Code starts a sandbox for the session, works in `/home/user`, and ends the sandbox when you quit. To keep working in the same machine, pass its id with `--sandbox-id sbx-...`. To start from a snapshot you saved, pass `--sandbox-snapshot-name my-snapshot`.
|
|
109
|
+
|
|
110
|
+
To set Maritime options for every session, declare the provider in `~/.deepagents/config.toml`. Deep Agents Code reads `params` only from a declared provider, so keep the first three lines:
|
|
111
|
+
|
|
112
|
+
```toml
|
|
113
|
+
[sandboxes.providers.maritime]
|
|
114
|
+
class_path = "langchain_maritime.dcode:MaritimeProvider"
|
|
115
|
+
working_dir = "/home/user"
|
|
116
|
+
supports_snapshot_name = true
|
|
117
|
+
|
|
118
|
+
[sandboxes.providers.maritime.params]
|
|
119
|
+
size = "large"
|
|
120
|
+
idle_timeout_seconds = 3600
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## What the agent gets
|
|
124
|
+
|
|
125
|
+
- **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.
|
|
126
|
+
- **Real isolation.** Each sandbox is a microVM with its own kernel, filesystem, network and processes.
|
|
127
|
+
- **Root when it needs it.** Commands run as `user`, with passwordless `sudo` for installs.
|
|
128
|
+
- **Limits that clean up after you.** An idle timeout pauses or ends a forgotten sandbox, and `time_limit_seconds` ends it no matter what.
|
|
129
|
+
|
|
130
|
+
## Options
|
|
131
|
+
|
|
132
|
+
`MaritimeSandbox.create()` takes any [Maritime sandbox option](https://maritime.sh/docs/sandboxes):
|
|
133
|
+
|
|
134
|
+
| Option | Default | What it does |
|
|
135
|
+
| --- | --- | --- |
|
|
136
|
+
| `from_` | `base` | A saved snapshot, a template, or a public image to start from. |
|
|
137
|
+
| `size` | `small` | A preset: `small`, `medium`, `large` or `xlarge`. |
|
|
138
|
+
| `vcpu`, `memory_mib`, `disk_gib` | from `size` | Override the preset. |
|
|
139
|
+
| `env` | none | Environment variables for every command. |
|
|
140
|
+
| `idle_timeout_seconds` | Maritime's default | How long without activity before `on_idle` applies. |
|
|
141
|
+
| `on_idle` | `pause` | `pause` keeps the disk and resumes on the next call. `kill` ends the sandbox. |
|
|
142
|
+
| `time_limit_seconds` | none | End the sandbox this long after it starts. |
|
|
143
|
+
| `metadata` | none | Labels you can filter on when you list sandboxes. |
|
|
144
|
+
|
|
145
|
+
The backend itself takes `timeout`, the default seconds a command may run (30 minutes). A timeout of `0` waits as long as Maritime allows.
|
|
146
|
+
|
|
147
|
+
## Behavior
|
|
148
|
+
|
|
149
|
+
- Commands run with `bash -lc`. Output is stdout followed by `<stderr>...</stderr>` when there is any.
|
|
150
|
+
- A command that runs out of time returns exit code `124` with the output it printed so far.
|
|
151
|
+
- File errors use Deep Agents' codes (`file_not_found`, `is_directory`, `invalid_path`, `permission_denied`). Anything else, such as an ended sandbox or a billing limit, keeps Maritime's own message so the agent sees what really went wrong.
|
|
152
|
+
- Maritime's file API acts as the machine's administrator, so `download_files` can read a file the shell user cannot.
|
|
153
|
+
|
|
154
|
+
## Tested
|
|
155
|
+
|
|
156
|
+
The [Deep Agents standard sandbox suite](https://github.com/langchain-ai/langchain/tree/master/libs/standard-tests) runs against a real Maritime sandbox:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
MARITIME_API_KEY=mk_... uv run pytest -m live
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
On 2026-11-17, with `deepagents` 0.7.39, `maritime` 0.12 and `langchain-tests` 1.1.9, 77 of the 86 standard tests pass. The other 9 are marked as expected failures in [`conftest.py`](tests/integration_tests/conftest.py), each with its reason:
|
|
163
|
+
|
|
164
|
+
- 7 glob and write tests: `langchain-tests` 1.1.9 expects relative glob paths and a `write` that refuses existing files, while `deepagents` 0.7.x returns absolute paths and overwrites. A plain local `BaseSandbox` fails them the same way.
|
|
165
|
+
- 2 large-output tests call `python`, and the Maritime base image ships `python3` only.
|
|
166
|
+
|
|
167
|
+
The live tests also cover the Deep Agents Code provider: create, reconnect by id, delete, and a new sandbox from a saved snapshot.
|
|
168
|
+
|
|
169
|
+
The unit tests run without an account. They swap only the network calls, so commands really run and Deep Agents' read, write, edit and ls helpers execute for real:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
uv run pytest
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Compatibility
|
|
176
|
+
|
|
177
|
+
| Package | Versions |
|
|
178
|
+
| --- | --- |
|
|
179
|
+
| Python | 3.11 to 3.14 |
|
|
180
|
+
| `deepagents` | 0.7.34 and later 0.7.x |
|
|
181
|
+
| `deepagents-code` (optional) | 0.2.5 and later, on Python 3.14 |
|
|
182
|
+
| `maritime` | 0.11.x and 0.12.x |
|
|
183
|
+
|
|
184
|
+
## License
|
|
185
|
+
|
|
186
|
+
[MIT](LICENSE), from [Maritime](https://maritime.sh).
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://maritime.sh">
|
|
3
|
+
<picture>
|
|
4
|
+
<source media="(prefers-color-scheme: dark)" srcset="assets/maritime-mark-white.png">
|
|
5
|
+
<img src="assets/maritime-mark-black.png" width="64" alt="Maritime">
|
|
6
|
+
</picture>
|
|
7
|
+
</a>
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
<h1 align="center">langchain-maritime</h1>
|
|
11
|
+
|
|
12
|
+
<p align="center"><a href="https://pypi.org/project/langchain-maritime/"><img src="https://img.shields.io/pypi/v/langchain-maritime?style=flat-square&color=2563eb" alt="PyPI"></a> <a href="https://pypi.org/project/langchain-maritime/"><img src="https://img.shields.io/pypi/pyversions/langchain-maritime?style=flat-square" alt="Python versions"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0a0a0a?style=flat-square" alt="MIT license"></a> <a href="https://github.com/maritime-sh/langchain-maritime/actions/workflows/test.yml"><img src="https://img.shields.io/github/actions/workflow/status/maritime-sh/langchain-maritime/test.yml?branch=main&style=flat-square&label=tests" alt="Tests"></a> <a href="https://maritime.sh/docs"><img src="https://img.shields.io/badge/docs-maritime.sh-0a0a0a?style=flat-square" alt="Docs"></a> <a href="https://discord.gg/wvPAvXNZqm"><img src="https://img.shields.io/badge/Discord-join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a></p>
|
|
13
|
+
|
|
14
|
+
<p align="center">
|
|
15
|
+
<b>Run <a href="https://github.com/langchain-ai/deepagents">Deep Agents</a> on a real cloud computer from <a href="https://maritime.sh">Maritime</a>.</b><br>
|
|
16
|
+
Every file read, edit, search and shell command happens in the agent's own Linux sandbox, never on your machine.
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
<p align="center">
|
|
20
|
+
<a href="#quickstart">Quickstart</a> ·
|
|
21
|
+
<a href="#deep-agents-code">Deep Agents Code</a> ·
|
|
22
|
+
<a href="#options">Options</a> ·
|
|
23
|
+
<a href="#tested">Tested</a> ·
|
|
24
|
+
<a href="https://github.com/maritime-sh/agents">More agents on Maritime</a>
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
## Quickstart
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
pip install langchain-maritime langchain-openai
|
|
31
|
+
export MARITIME_API_KEY=mk_... # maritime.sh/settings/api-keys
|
|
32
|
+
export OPENAI_API_KEY=sk-...
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
from deepagents import create_deep_agent
|
|
37
|
+
from langchain_openai import ChatOpenAI
|
|
38
|
+
|
|
39
|
+
from langchain_maritime import MaritimeSandbox
|
|
40
|
+
|
|
41
|
+
backend = MaritimeSandbox.create(idle_timeout_seconds=600)
|
|
42
|
+
try:
|
|
43
|
+
agent = create_deep_agent(model=ChatOpenAI(model="gpt-5.4"), backend=backend)
|
|
44
|
+
result = agent.invoke(
|
|
45
|
+
{
|
|
46
|
+
"messages": [
|
|
47
|
+
{
|
|
48
|
+
"role": "user",
|
|
49
|
+
"content": "Write primes.py that prints 10 primes, run it, show me the output.",
|
|
50
|
+
}
|
|
51
|
+
]
|
|
52
|
+
}
|
|
53
|
+
)
|
|
54
|
+
print(result["messages"][-1].content)
|
|
55
|
+
finally:
|
|
56
|
+
backend.kill()
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
`MaritimeSandbox.create()` starts a fresh sandbox in a few seconds. The agent's `ls`, `read_file`, `write_file`, `edit_file`, `glob`, `grep` and `execute` tools all run inside it.
|
|
60
|
+
|
|
61
|
+
Already have a sandbox? Wrap it:
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
from maritime import Maritime
|
|
65
|
+
|
|
66
|
+
sandbox = Maritime().sandboxes.get("sbx-...")
|
|
67
|
+
backend = MaritimeSandbox(sandbox=sandbox)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
The runnable version is [`examples/deep_agent.py`](examples/deep_agent.py). No OpenAI account? [Maritime LLM](https://maritime.sh/docs/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`.
|
|
71
|
+
|
|
72
|
+
## Deep Agents Code
|
|
73
|
+
|
|
74
|
+
Installing this package adds a `maritime` sandbox to [Deep Agents Code](https://github.com/langchain-ai/deepagents/tree/main/libs/code). No config needed:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
dcode install langchain-maritime --package
|
|
78
|
+
export MARITIME_API_KEY=mk_...
|
|
79
|
+
dcode --sandbox maritime
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Deep Agents Code starts a sandbox for the session, works in `/home/user`, and ends the sandbox when you quit. To keep working in the same machine, pass its id with `--sandbox-id sbx-...`. To start from a snapshot you saved, pass `--sandbox-snapshot-name my-snapshot`.
|
|
83
|
+
|
|
84
|
+
To set Maritime options for every session, declare the provider in `~/.deepagents/config.toml`. Deep Agents Code reads `params` only from a declared provider, so keep the first three lines:
|
|
85
|
+
|
|
86
|
+
```toml
|
|
87
|
+
[sandboxes.providers.maritime]
|
|
88
|
+
class_path = "langchain_maritime.dcode:MaritimeProvider"
|
|
89
|
+
working_dir = "/home/user"
|
|
90
|
+
supports_snapshot_name = true
|
|
91
|
+
|
|
92
|
+
[sandboxes.providers.maritime.params]
|
|
93
|
+
size = "large"
|
|
94
|
+
idle_timeout_seconds = 3600
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
## What the agent gets
|
|
98
|
+
|
|
99
|
+
- **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.
|
|
100
|
+
- **Real isolation.** Each sandbox is a microVM with its own kernel, filesystem, network and processes.
|
|
101
|
+
- **Root when it needs it.** Commands run as `user`, with passwordless `sudo` for installs.
|
|
102
|
+
- **Limits that clean up after you.** An idle timeout pauses or ends a forgotten sandbox, and `time_limit_seconds` ends it no matter what.
|
|
103
|
+
|
|
104
|
+
## Options
|
|
105
|
+
|
|
106
|
+
`MaritimeSandbox.create()` takes any [Maritime sandbox option](https://maritime.sh/docs/sandboxes):
|
|
107
|
+
|
|
108
|
+
| Option | Default | What it does |
|
|
109
|
+
| --- | --- | --- |
|
|
110
|
+
| `from_` | `base` | A saved snapshot, a template, or a public image to start from. |
|
|
111
|
+
| `size` | `small` | A preset: `small`, `medium`, `large` or `xlarge`. |
|
|
112
|
+
| `vcpu`, `memory_mib`, `disk_gib` | from `size` | Override the preset. |
|
|
113
|
+
| `env` | none | Environment variables for every command. |
|
|
114
|
+
| `idle_timeout_seconds` | Maritime's default | How long without activity before `on_idle` applies. |
|
|
115
|
+
| `on_idle` | `pause` | `pause` keeps the disk and resumes on the next call. `kill` ends the sandbox. |
|
|
116
|
+
| `time_limit_seconds` | none | End the sandbox this long after it starts. |
|
|
117
|
+
| `metadata` | none | Labels you can filter on when you list sandboxes. |
|
|
118
|
+
|
|
119
|
+
The backend itself takes `timeout`, the default seconds a command may run (30 minutes). A timeout of `0` waits as long as Maritime allows.
|
|
120
|
+
|
|
121
|
+
## Behavior
|
|
122
|
+
|
|
123
|
+
- Commands run with `bash -lc`. Output is stdout followed by `<stderr>...</stderr>` when there is any.
|
|
124
|
+
- A command that runs out of time returns exit code `124` with the output it printed so far.
|
|
125
|
+
- File errors use Deep Agents' codes (`file_not_found`, `is_directory`, `invalid_path`, `permission_denied`). Anything else, such as an ended sandbox or a billing limit, keeps Maritime's own message so the agent sees what really went wrong.
|
|
126
|
+
- Maritime's file API acts as the machine's administrator, so `download_files` can read a file the shell user cannot.
|
|
127
|
+
|
|
128
|
+
## Tested
|
|
129
|
+
|
|
130
|
+
The [Deep Agents standard sandbox suite](https://github.com/langchain-ai/langchain/tree/master/libs/standard-tests) runs against a real Maritime sandbox:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
MARITIME_API_KEY=mk_... uv run pytest -m live
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
On 2026-11-17, with `deepagents` 0.7.39, `maritime` 0.12 and `langchain-tests` 1.1.9, 77 of the 86 standard tests pass. The other 9 are marked as expected failures in [`conftest.py`](tests/integration_tests/conftest.py), each with its reason:
|
|
137
|
+
|
|
138
|
+
- 7 glob and write tests: `langchain-tests` 1.1.9 expects relative glob paths and a `write` that refuses existing files, while `deepagents` 0.7.x returns absolute paths and overwrites. A plain local `BaseSandbox` fails them the same way.
|
|
139
|
+
- 2 large-output tests call `python`, and the Maritime base image ships `python3` only.
|
|
140
|
+
|
|
141
|
+
The live tests also cover the Deep Agents Code provider: create, reconnect by id, delete, and a new sandbox from a saved snapshot.
|
|
142
|
+
|
|
143
|
+
The unit tests run without an account. They swap only the network calls, so commands really run and Deep Agents' read, write, edit and ls helpers execute for real:
|
|
144
|
+
|
|
145
|
+
```bash
|
|
146
|
+
uv run pytest
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
## Compatibility
|
|
150
|
+
|
|
151
|
+
| Package | Versions |
|
|
152
|
+
| --- | --- |
|
|
153
|
+
| Python | 3.11 to 3.14 |
|
|
154
|
+
| `deepagents` | 0.7.34 and later 0.7.x |
|
|
155
|
+
| `deepagents-code` (optional) | 0.2.5 and later, on Python 3.14 |
|
|
156
|
+
| `maritime` | 0.11.x and 0.12.x |
|
|
157
|
+
|
|
158
|
+
## License
|
|
159
|
+
|
|
160
|
+
[MIT](LICENSE), from [Maritime](https://maritime.sh).
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
"""A Deep Agent whose files and shell live on a Maritime sandbox.
|
|
2
|
+
|
|
3
|
+
pip install langchain-maritime langchain-openai
|
|
4
|
+
export MARITIME_API_KEY=... # maritime.sh/settings/api-keys
|
|
5
|
+
export OPENAI_API_KEY=... # an OpenAI key, or a Maritime LLM token
|
|
6
|
+
export OPENAI_BASE_URL=https://api.maritime.sh/api/llm/v1 # only for Maritime LLM
|
|
7
|
+
python examples/deep_agent.py
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
import os
|
|
11
|
+
|
|
12
|
+
from deepagents import create_deep_agent
|
|
13
|
+
from langchain_openai import ChatOpenAI
|
|
14
|
+
|
|
15
|
+
from langchain_maritime import MaritimeSandbox
|
|
16
|
+
|
|
17
|
+
TASK = (
|
|
18
|
+
"In /home/user/project, write primes.py that prints the first 10 prime numbers, one per line. "
|
|
19
|
+
"Run it, then tell me the output and the Python version on this machine."
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
|
|
23
|
+
def main() -> None:
|
|
24
|
+
backend = MaritimeSandbox.create(idle_timeout_seconds=600, on_idle="kill")
|
|
25
|
+
print(f"sandbox {backend.id}")
|
|
26
|
+
try:
|
|
27
|
+
agent = create_deep_agent(
|
|
28
|
+
model=ChatOpenAI(model=os.environ.get("MODEL", "gpt-5.4")),
|
|
29
|
+
system_prompt="You work on a Linux machine. Use your file and shell tools, then answer briefly.",
|
|
30
|
+
backend=backend,
|
|
31
|
+
)
|
|
32
|
+
result = agent.invoke({"messages": [{"role": "user", "content": TASK}]})
|
|
33
|
+
for message in result["messages"]:
|
|
34
|
+
for call in getattr(message, "tool_calls", None) or []:
|
|
35
|
+
print(f"> {call['name']} {call['args']}")
|
|
36
|
+
print("\n" + result["messages"][-1].content)
|
|
37
|
+
print("\nOn the sandbox:\n" + backend.execute("cat /home/user/project/primes.py").output)
|
|
38
|
+
finally:
|
|
39
|
+
backend.kill()
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
if __name__ == "__main__":
|
|
43
|
+
main()
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.1.0"
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
"""`dcode --sandbox maritime`: the Maritime provider for Deep Agents Code.
|
|
2
|
+
|
|
3
|
+
Installing `langchain-maritime` registers this provider under the
|
|
4
|
+
`deepagents_code.sandbox_providers` entry point, so Deep Agents Code finds it
|
|
5
|
+
without any config:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
dcode install langchain-maritime --package
|
|
9
|
+
export MARITIME_API_KEY=mk_...
|
|
10
|
+
dcode --sandbox maritime
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
This module imports `deepagents_code`, which only Deep Agents Code installs.
|
|
14
|
+
Deep Agents itself never loads it.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
import os
|
|
20
|
+
from typing import TYPE_CHECKING, Any
|
|
21
|
+
|
|
22
|
+
from deepagents_code.integrations.sandbox_provider import (
|
|
23
|
+
SandboxInstallHint,
|
|
24
|
+
SandboxNotFoundError,
|
|
25
|
+
SandboxProvider,
|
|
26
|
+
SandboxProviderMetadata,
|
|
27
|
+
)
|
|
28
|
+
from maritime import Maritime, MaritimeSandboxError
|
|
29
|
+
|
|
30
|
+
from langchain_maritime.sandbox import MaritimeSandbox
|
|
31
|
+
|
|
32
|
+
if TYPE_CHECKING:
|
|
33
|
+
from deepagents.backends.protocol import SandboxBackendProtocol
|
|
34
|
+
|
|
35
|
+
WORKING_DIR = "/home/user"
|
|
36
|
+
"""The sandbox user's home, where Deep Agents Code starts."""
|
|
37
|
+
|
|
38
|
+
_CREATE_OPTIONS = frozenset(
|
|
39
|
+
{
|
|
40
|
+
"size",
|
|
41
|
+
"vcpu",
|
|
42
|
+
"memory_mib",
|
|
43
|
+
"disk_gib",
|
|
44
|
+
"env",
|
|
45
|
+
"metadata",
|
|
46
|
+
"name",
|
|
47
|
+
"end_user",
|
|
48
|
+
"idle_timeout_seconds",
|
|
49
|
+
"on_idle",
|
|
50
|
+
"time_limit_seconds",
|
|
51
|
+
}
|
|
52
|
+
)
|
|
53
|
+
_GONE = frozenset({"resource_not_found", "sandbox_ended", "not_found"})
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _api_key() -> str | None:
|
|
57
|
+
return os.environ.get("DEEPAGENTS_CODE_MARITIME_API_KEY") or os.environ.get("MARITIME_API_KEY")
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
class MaritimeProvider(SandboxProvider):
|
|
61
|
+
"""Creates and ends Maritime sandboxes for Deep Agents Code."""
|
|
62
|
+
|
|
63
|
+
def __init__(self, *, client: Maritime | None = None) -> None:
|
|
64
|
+
"""Connect to Maritime.
|
|
65
|
+
|
|
66
|
+
Args:
|
|
67
|
+
client: A Maritime client. Defaults to one built from
|
|
68
|
+
`MARITIME_API_KEY` (or `DEEPAGENTS_CODE_MARITIME_API_KEY`).
|
|
69
|
+
|
|
70
|
+
Raises:
|
|
71
|
+
ValueError: If no API key is set.
|
|
72
|
+
"""
|
|
73
|
+
if client is None:
|
|
74
|
+
key = _api_key()
|
|
75
|
+
if not key:
|
|
76
|
+
msg = (
|
|
77
|
+
"No Maritime API key found. Set MARITIME_API_KEY "
|
|
78
|
+
"(or DEEPAGENTS_CODE_MARITIME_API_KEY). Create one at maritime.sh/settings/api-keys."
|
|
79
|
+
)
|
|
80
|
+
raise ValueError(msg)
|
|
81
|
+
client = Maritime(api_key=key)
|
|
82
|
+
self._client = client
|
|
83
|
+
|
|
84
|
+
@property
|
|
85
|
+
def metadata(self) -> SandboxProviderMetadata:
|
|
86
|
+
"""How Deep Agents Code should describe and use this provider."""
|
|
87
|
+
return SandboxProviderMetadata(
|
|
88
|
+
name="maritime",
|
|
89
|
+
working_dir=WORKING_DIR,
|
|
90
|
+
install=SandboxInstallHint(kind="package", name="langchain-maritime"),
|
|
91
|
+
supports_sandbox_id=True,
|
|
92
|
+
supports_snapshot_name=True,
|
|
93
|
+
backend_module="langchain_maritime",
|
|
94
|
+
)
|
|
95
|
+
|
|
96
|
+
def get_or_create(
|
|
97
|
+
self,
|
|
98
|
+
*,
|
|
99
|
+
sandbox_id: str | None = None,
|
|
100
|
+
snapshot: str | None = None,
|
|
101
|
+
timeout: int = 30 * 60,
|
|
102
|
+
**kwargs: Any, # noqa: ANN401 # validated against _CREATE_OPTIONS
|
|
103
|
+
) -> SandboxBackendProtocol:
|
|
104
|
+
"""Connect to a sandbox by id or name, or create a new one.
|
|
105
|
+
|
|
106
|
+
Args:
|
|
107
|
+
sandbox_id: An existing sandbox id or name. None creates one.
|
|
108
|
+
snapshot: A saved snapshot or template to start a new sandbox from.
|
|
109
|
+
timeout: Default command timeout in seconds.
|
|
110
|
+
**kwargs: Maritime create options from your Deep Agents Code
|
|
111
|
+
config, such as `size`, `idle_timeout_seconds` or `env`.
|
|
112
|
+
|
|
113
|
+
Returns:
|
|
114
|
+
A `MaritimeSandbox` backend.
|
|
115
|
+
|
|
116
|
+
Raises:
|
|
117
|
+
TypeError: If an option is not a Maritime create option.
|
|
118
|
+
ValueError: If `snapshot` is combined with `sandbox_id`.
|
|
119
|
+
SandboxNotFoundError: If `sandbox_id` does not exist or has ended.
|
|
120
|
+
"""
|
|
121
|
+
unknown = sorted(set(kwargs) - _CREATE_OPTIONS)
|
|
122
|
+
if unknown:
|
|
123
|
+
msg = f"Received unsupported arguments: {unknown}"
|
|
124
|
+
raise TypeError(msg)
|
|
125
|
+
if sandbox_id is not None:
|
|
126
|
+
if snapshot is not None:
|
|
127
|
+
msg = "snapshot only applies when creating a new sandbox"
|
|
128
|
+
raise ValueError(msg)
|
|
129
|
+
try:
|
|
130
|
+
sandbox = self._client.sandboxes.get(sandbox_id)
|
|
131
|
+
except MaritimeSandboxError as exc:
|
|
132
|
+
if exc.code in _GONE:
|
|
133
|
+
msg = f"Maritime sandbox {sandbox_id!r} was not found"
|
|
134
|
+
raise SandboxNotFoundError(msg) from exc
|
|
135
|
+
raise
|
|
136
|
+
if sandbox.state == "ended":
|
|
137
|
+
msg = f"Maritime sandbox {sandbox_id!r} has ended"
|
|
138
|
+
raise SandboxNotFoundError(msg)
|
|
139
|
+
return MaritimeSandbox(sandbox=sandbox, timeout=timeout)
|
|
140
|
+
|
|
141
|
+
options: dict[str, Any] = {"idle_timeout_seconds": 1800, "on_idle": "pause", **kwargs}
|
|
142
|
+
options.setdefault("metadata", {}).setdefault("created_by", "deepagents-code")
|
|
143
|
+
sandbox = self._client.sandboxes.create(from_=snapshot, **options)
|
|
144
|
+
return MaritimeSandbox(sandbox=sandbox, timeout=timeout)
|
|
145
|
+
|
|
146
|
+
def delete(self, *, sandbox_id: str, **kwargs: Any) -> None: # noqa: ARG002, ANN401 # interface signature
|
|
147
|
+
"""End a sandbox. A sandbox that is already gone counts as deleted."""
|
|
148
|
+
try:
|
|
149
|
+
self._client.sandboxes.get(sandbox_id).kill()
|
|
150
|
+
except MaritimeSandboxError as exc:
|
|
151
|
+
if exc.code not in _GONE:
|
|
152
|
+
raise
|
|
File without changes
|