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.
@@ -0,0 +1,11 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ .pytest_cache/
5
+ .mypy_cache/
6
+ .ruff_cache/
7
+ dist/
8
+ build/
9
+ *.egg-info/
10
+ .env
11
+ .DS_Store
@@ -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,6 @@
1
+ """Maritime sandboxes for Deep Agents."""
2
+
3
+ from langchain_maritime._version import __version__
4
+ from langchain_maritime.sandbox import MaritimeSandbox
5
+
6
+ __all__ = ["MaritimeSandbox", "__version__"]
@@ -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