modal-devin 0.1.0__tar.gz

modal_devin-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

modal_devin-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Summary
+
+Describe the user-facing behavior and why it belongs in `modal-devin`.
+
+## Verification
+
+- [ ] Lifecycle behavior has network-free tests.
+- [ ] `uv run coverage run -m pytest -q` and `uv run coverage report` pass.
+- [ ] Ruff formatting, Ruff lint, `ty`, and package builds pass.
+- [ ] No credential is present in arguments, logs, generated code, or image metadata.
+- [ ] Public API and changelog documentation are updated when applicable.

modal_devin-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,73 @@
+name: CI
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  tests:
+    name: Test Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --dev
+      - run: uv run pytest -q
+
+  quality:
+    name: Quality and package
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - run: uv sync --dev
+      - run: uv run coverage run -m pytest -q
+      - run: uv run coverage report
+      - run: uv run ruff format --check .
+      - run: uv run ruff check .
+      - run: uv run ty check --error all .
+      - run: uv build
+      - name: Smoke-test the built wheel
+        run: |
+          tmpdir="$(mktemp -d)"
+          cd "$tmpdir"
+          uv run --isolated --with "$GITHUB_WORKSPACE"/dist/*.whl \
+            python -c "from modal_devin import Worker; assert Worker('smoke', pool_id='pool').name == 'smoke'"
+
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+      - run: npx -y mint broken-links

modal_devin-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/modal-devin/
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+
+      - name: Verify release tag matches package version
+        run: |
+          version="$(uv run python -c 'import modal_devin; print(modal_devin.__version__)')"
+          test "${GITHUB_REF_NAME#v}" = "$version"
+      - run: uv build
+      - run: uv run --with twine twine check dist/*
+      - run: uv publish --trusted-publishing always dist/*

modal_devin-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+modal-devin-test/
+pools/

modal_devin-0.1.0/.mintignore

@@ -0,0 +1,9 @@
+.git/
+.github/
+.venv/
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+*.egg-info/
+modal_devin/
+tests/

modal_devin-0.1.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes are documented here. The project follows Keep a Changelog
+and uses semantic versioning.
+
+## Unreleased
+
+### Added
+
+- `Worker` as an immutable configured runtime with durable image, session, and
+  dispatch operations.
+- Validated `WorkerSettings` with explicit `MODAL_DEVIN_*` environment loading.
+- Typed public exceptions for configuration, compatibility, API, status, and
+  worker-process failures.
+- `modal-devin init`, `deploy`, and `doctor` project-level commands.
+- Modal Dict-backed filesystem snapshot persistence.
+
+### Changed
+
+- Generated files now own the `modal.App`, secret, image composition, function
+  decorators, schedule, and connection between the scheduler and session function.
+- Session and scheduler bodies are thin adapters into `Worker.run_session()` and
+  `Worker.dispatch_pending_sessions()`.
+- Claims are acquired inside the spawned session invocation rather than before the
+  asynchronous Modal dispatch, so queue delays and function retries do not reuse a
+  stale claim.
+- Outposts session states are parsed into a closed protocol type; malformed or new
+  states preserve recovery data instead of being treated as completed.
+- Scheduler functions use a lightweight controller image instead of the full Devin
+  worker image.
+- Sidecar image cache entries are versioned by the sidecar recipe digest.
+- `Worker.run_session()` inherits Modal Sandbox keyword typing through `ParamSpec`
+  while protecting runtime-owned lifecycle options.
+- Deployed functions are named `scheduler` and `session` by operational role.
+- Worker images remain composable between `Worker.base_image()` and the terminal
+  `Worker.prepare_image()` source mount.
+- Final session status failures preserve a recovery snapshot and fail the Modal
+  invocation.
+- Nonzero Devin worker exits now raise `WorkerExitedError`.
+- Outer function timeouts now account for status requests and backoff, sidecar
+  readiness, snapshot creation, claim release, and cleanup.
+- The Devin worker command receives the configured session timeout directly, while
+  the containing Sandbox receives a larger lifecycle budget for startup and recovery.
+- Scheduler transport, protocol, image-build, and dispatch failures now fail the
+  scheduled invocation after attempting every independent dispatch.
+- Pending session dispatches use bounded leases to avoid duplicate Modal queue entries.
+- Snapshot index entries are refreshed daily while the scheduler is deployed, keeping
+  their retention aligned with 30-day or indefinite filesystem snapshots.
+- Package installation is documented as a project dependency rather than an
+  isolated tool installation.
+- Scheduler invocations now surface protocol, sidecar-build, and dispatch failures;
+  all pending sessions are still attempted before dispatch errors are reported.
+- Devin CLI installation failures now stop worker image builds at the failing
+  installer step.
+
+### Removed
+
+- The `Worker.app()` application factory and its Modal function-option mappings.
+- The low-level public `poll_and_dispatch()`, `build_sidecar_image_id()`,
+  `SessionRunner`, and `OutpostPoolConfig` surface.
+- The redundant `modal-devin outpost` command group.
+- The `clone_private_repo()` image-build helper.
+
+### Security
+
+- Interactive Modal Secret creation now uses the public Modal SDK directly, keeping
+  the Devin service key in memory instead of writing a temporary JSON file or
+  invoking a secret-creation subprocess.
+- Secret discovery now uses the public Modal SDK instead of parsing subprocess JSON,
+  and credential setup documentation no longer stages tokens in local files.
+- The sidecar health check is served locally and no longer sends a token-bearing
+  request to the upstream API.
+- The credential-injecting proxy only forwards Outposts API paths.
+- Worker output combines stdout and stderr so failures remain observable.

modal_devin-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Code of Conduct
+
+We are committed to a welcoming, harassment-free project for everyone.
+
+Be respectful, assume good intent, give actionable technical feedback, and make
+room for people with different backgrounds and levels of experience. Harassment,
+personal attacks, discriminatory language, unwanted sexual attention, and the
+publication of another person's private information are not acceptable.
+
+Maintainers may edit or remove contributions and restrict participation when
+behavior threatens the safety or productivity of the community. Report conduct
+concerns privately through the repository owner's GitHub profile. Reports will
+be handled as confidentially as practical.

modal_devin-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing
+
+Thanks for helping improve `modal-devin`.
+
+## Setup
+
+```bash
+uv sync --dev
+```
+
+## Architecture
+
+`Worker` is the supported user-facing abstraction. Keep lifecycle and upstream
+integration details behind the following private boundaries:
+
+- `_config.py`: validated settings and resource identities;
+- `_client.py`: Devin Outposts HTTP contract;
+- `_runtime.py`: claim, dispatch, execution, and recovery state machine;
+- `images.py`: composable public image helpers and sidecar compatibility;
+- `worker.py`: the small public runtime and image API;
+- `templates/pool.py.tmpl`: the user-owned Modal application composition root.
+
+Generated applications should use Modal's native `App` and `@app.function`
+vocabulary. Do not expose sidecar image IDs, raw tokens, raw HTTP payloads, or
+Modal Dicts through the public API.
+
+`Worker.run_session()` deliberately derives its option signature from
+`modal.Sandbox.create` with `ParamSpec`. Keep its runtime validation narrower than
+Modal's full constructor: modal-devin owns command arguments, timeout, workdir, and
+the readiness probe.
+
+The scheduler may discover and spawn pending session IDs, but it must not acquire
+their Outposts claims. Claiming belongs inside the spawned session invocation so a
+Modal queue delay or retry cannot outlive the claim deadline. Unknown upstream
+status values must fail closed and preserve a recovery snapshot.
+
+Keep the generated scheduler at `max_containers=1`. Dispatch leases are acquired
+before spawning and cleared when the session invocation starts; serialized scheduler
+runs make stale-lease replacement deterministic. Scheduler failures must propagate so
+Modal can alert and apply configured retries.
+
+The sidecar image cache key includes the Caddy configuration, install recipe, and
+`_SIDECAR_RECIPE_SCHEMA`. Bump that schema whenever `_sidecar_image()` changes in a
+way not represented by the embedded inputs.
+
+## Checks
+
+Run the same checks as CI:
+
+```bash
+uv run coverage run -m pytest -q
+uv run coverage report
+uv run ruff format --check .
+uv run ruff check .
+uv run ty check --error all .
+uv build
+```
+
+Tests that require live Modal or Devin credentials must be opt-in and must not
+claim production sessions. Every runtime change should also have a network-free
+lifecycle test covering cleanup and claim release.
+
+To verify real Modal serialization and image hydration in a disposable workspace:
+
+```bash
+MODAL_DEVIN_RUN_MODAL_INTEGRATION=1 uv run pytest -m integration -q
+```
+
+The integration test creates an ephemeral Modal app and does not contact Devin.
+
+## Security
+
+Never put credentials in command arguments, logs, generated files, image-layer
+metadata, or Git remote URLs. Report vulnerabilities using `SECURITY.md` rather
+than a public issue.

modal_devin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 modal-devin contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modal_devin-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: modal-devin
+Version: 0.1.0
+Summary: Run Devin Outposts workers on Modal
+Project-URL: Repository, https://github.com/aaazzam/modal-devin
+Project-URL: Issues, https://github.com/aaazzam/modal-devin/issues
+Project-URL: Changelog, https://github.com/aaazzam/modal-devin/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/aaazzam/modal-devin#readme
+Author-email: Adam Azzam <33043305+aaazzam@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: devin,modal,outposts,workers
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cyclopts>=4.20
+Requires-Dist: modal<2,>=1.5.1
+Requires-Dist: rich>=13.6
+Description-Content-Type: text/markdown
+
+# modal-devin
+
+Run Devin Outposts sessions on Modal.
+
+Devin's planning remains in Devin Cloud while commands, file edits, and repository
+access run in isolated [Modal Sandboxes](https://modal.com/docs/guide/sandboxes) that
+you control. `modal-devin` provides the orchestrator: it watches your Outposts pool,
+starts a Sandbox for each session, preserves suspended work, and cleans up when the
+session ends.
+
+> [!NOTE]
+> `modal-devin` is alpha software. Until the first stable release, only the latest
+> release on the default branch receives security fixes.
+
+## When to use it
+
+Use `modal-devin` when you want Devin sessions to:
+
+- Run with custom tools, repositories, and system packages.
+- Reach services and registries available from your Modal environment.
+- Use Modal compute, memory, and region controls.
+- Resume from a preserved workspace after suspension.
+- Fit into an existing Python and Modal deployment workflow.
+
+## How it fits into Outposts
+
+Outposts separates the worker from the orchestrator:
+
+- The **worker** executes one Devin session. `modal-devin` runs it inside a Modal
+  Sandbox.
+- The **orchestrator** finds queued sessions and manages their compute lifecycle.
+  `modal-devin` deploys this layer as a Modal application.
+
+Workers need outbound HTTPS access to Devin. They do not require inbound ports or a
+public IP.
+
+## Quick start
+
+You need Python 3.11 or newer, a configured Modal account, an Outposts pool ID, and
+a Devin token authorized for that pool.
+
+```bash
+uv add modal-devin
+uv run modal setup
+uv run modal-devin init my-pool --pool-id outpost_env-...
+uv run modal-devin doctor
+uv run modal-devin deploy pools/my_pool.py
+```
+
+Run `uv run modal-devin init` without arguments to create a pool interactively.
+
+The generated Python file is your Modal application. Edit it to choose the workspace
+image, secrets, compute, region, retry policy, and schedule. The library manages the
+Outposts and Sandbox lifecycle behind that application.
+
+## Customize the workspace
+
+Add packages and project source to the generated image block, before
+`prepare_image()`:
+
+```python
+base_image = (
+    worker.base_image()
+    .apt_install("ripgrep")
+    .run_commands(
+        "git clone https://github.com/your-org/app /root/workspace/app"
+    )
+)
+image = worker.prepare_image(base_image)
+```
+
+## Documentation
+
+Full tutorials, how-to guides, and reference docs live in this repository under
+`tutorials/`, `guides/`, `explanation/`, and `reference/`. They're written for the
+project's Mintlify site, which isn't published yet, so some page components won't
+render when viewed directly on GitHub:
+
+- [Deploy your first worker](tutorials/first-worker.mdx)
+- [Build a project workspace](tutorials/custom-workspace.mdx)
+- [Configure resources and regions](guides/resources-and-regions.mdx)
+- [Operate a deployed worker](guides/operate-a-worker.mdx)
+- [Security model](explanation/security.mdx)
+
+## Security
+
+Use a least-privilege Devin service user and separate credentials for environments
+with different trust requirements. The session workload does not receive the raw
+Outposts token in its environment, although it can exercise the Outposts capability
+required to serve its assigned session.
+
+Report vulnerabilities through
+[GitHub private vulnerability reporting](https://github.com/aaazzam/modal-devin/security).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development and test workflow.

modal_devin-0.1.0/README.md

@@ -0,0 +1,97 @@
+# modal-devin
+
+Run Devin Outposts sessions on Modal.
+
+Devin's planning remains in Devin Cloud while commands, file edits, and repository
+access run in isolated [Modal Sandboxes](https://modal.com/docs/guide/sandboxes) that
+you control. `modal-devin` provides the orchestrator: it watches your Outposts pool,
+starts a Sandbox for each session, preserves suspended work, and cleans up when the
+session ends.
+
+> [!NOTE]
+> `modal-devin` is alpha software. Until the first stable release, only the latest
+> release on the default branch receives security fixes.
+
+## When to use it
+
+Use `modal-devin` when you want Devin sessions to:
+
+- Run with custom tools, repositories, and system packages.
+- Reach services and registries available from your Modal environment.
+- Use Modal compute, memory, and region controls.
+- Resume from a preserved workspace after suspension.
+- Fit into an existing Python and Modal deployment workflow.
+
+## How it fits into Outposts
+
+Outposts separates the worker from the orchestrator:
+
+- The **worker** executes one Devin session. `modal-devin` runs it inside a Modal
+  Sandbox.
+- The **orchestrator** finds queued sessions and manages their compute lifecycle.
+  `modal-devin` deploys this layer as a Modal application.
+
+Workers need outbound HTTPS access to Devin. They do not require inbound ports or a
+public IP.
+
+## Quick start
+
+You need Python 3.11 or newer, a configured Modal account, an Outposts pool ID, and
+a Devin token authorized for that pool.
+
+```bash
+uv add modal-devin
+uv run modal setup
+uv run modal-devin init my-pool --pool-id outpost_env-...
+uv run modal-devin doctor
+uv run modal-devin deploy pools/my_pool.py
+```
+
+Run `uv run modal-devin init` without arguments to create a pool interactively.
+
+The generated Python file is your Modal application. Edit it to choose the workspace
+image, secrets, compute, region, retry policy, and schedule. The library manages the
+Outposts and Sandbox lifecycle behind that application.
+
+## Customize the workspace
+
+Add packages and project source to the generated image block, before
+`prepare_image()`:
+
+```python
+base_image = (
+    worker.base_image()
+    .apt_install("ripgrep")
+    .run_commands(
+        "git clone https://github.com/your-org/app /root/workspace/app"
+    )
+)
+image = worker.prepare_image(base_image)
+```
+
+## Documentation
+
+Full tutorials, how-to guides, and reference docs live in this repository under
+`tutorials/`, `guides/`, `explanation/`, and `reference/`. They're written for the
+project's Mintlify site, which isn't published yet, so some page components won't
+render when viewed directly on GitHub:
+
+- [Deploy your first worker](tutorials/first-worker.mdx)
+- [Build a project workspace](tutorials/custom-workspace.mdx)
+- [Configure resources and regions](guides/resources-and-regions.mdx)
+- [Operate a deployed worker](guides/operate-a-worker.mdx)
+- [Security model](explanation/security.mdx)
+
+## Security
+
+Use a least-privilege Devin service user and separate credentials for environments
+with different trust requirements. The session workload does not receive the raw
+Outposts token in its environment, although it can exercise the Outposts capability
+required to serve its assigned session.
+
+Report vulnerabilities through
+[GitHub private vulnerability reporting](https://github.com/aaazzam/modal-devin/security).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the development and test workflow.

modal_devin-0.1.0/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Supported versions
+
+Until the first stable release, only the latest release on the default branch is
+supported with security fixes.
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability reporting for this repository. Do not
+open a public issue or include live Devin, Modal, or repository credentials in a
+report.
+
+Include the affected version, reproduction steps, expected impact, and whether
+you believe a credential or customer workload was exposed. You should receive
+an acknowledgement within five business days.

modal_devin-0.1.0/docs.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "mint",
+  "name": "modal-devin",
+  "description": "Run secure, resumable Devin Outposts workers on Modal.",
+  "colors": {
+    "primary": "#3730A3",
+    "light": "#A5B4FC",
+    "dark": "#6366F1"
+  },
+  "navigation": {
+    "groups": [
+      {
+        "group": "Start here",
+        "icon": "house",
+        "pages": [
+          "index"
+        ]
+      },
+      {
+        "group": "Tutorials",
+        "icon": "graduation-cap",
+        "pages": [
+          "tutorials/first-worker",
+          "tutorials/create-a-pool",
+          "tutorials/custom-workspace"
+        ]
+      },
+      {
+        "group": "How-to guides",
+        "icon": "screwdriver-wrench",
+        "pages": [
+          "guides/customize-image",
+          "guides/resources-and-regions",
+          "guides/runtime-configuration",
+          "guides/multiple-pools",
+          "guides/operate-a-worker",
+          "guides/troubleshooting"
+        ]
+      },
+      {
+        "group": "Concepts",
+        "icon": "lightbulb",
+        "pages": [
+          "explanation/architecture",
+          "explanation/resumability",
+          "explanation/security",
+          "explanation/session-lifecycle",
+          "explanation/timeouts"
+        ]
+      },
+      {
+        "group": "Reference",
+        "icon": "book-open",
+        "pages": [
+          "reference/cli",
+          "reference/worker",
+          "reference/settings",
+          "reference/images",
+          "reference/exceptions",
+          "reference/generated-application"
+        ]
+      }
+    ]
+  },
+  "navbar": {
+    "links": [
+      {
+        "label": "GitHub",
+        "href": "https://github.com/aaazzam/modal-devin"
+      }
+    ],
+    "primary": {
+      "type": "github",
+      "href": "https://github.com/aaazzam/modal-devin"
+    }
+  },
+  "footer": {
+    "socials": {
+      "github": "https://github.com/aaazzam/modal-devin"
+    }
+  },
+  "contextual": {
+    "options": [
+      "copy",
+      "view",
+      "chatgpt",
+      "claude"
+    ]
+  },
+  "styling": {
+    "eyebrows": "breadcrumbs"
+  }
+}