> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Amp Orbs

> Run Amp self-hosted orbs on Namespace Devboxes.

[Amp](https://ampcode.com) can use Namespace Devboxes for [self-hosted orbs](https://ampcode.com/docs/orbs/self-hosted). Each thread gets its own Devbox for terminal commands, file edits, builds, and tests. Amp runs the agent loop and model inference; Namespace runs the tools and stores the orb's files.

## Getting Started

### Requirements

* A [Namespace account](https://cloud.namespace.so).
* An [Amp workspace](https://ampcode.com/docs/collaborate/workspaces) where you can add an orb provider.
* A Linux or macOS machine to run the orb dispatcher. Keep this machine running and connected to the internet. The orbs themselves run on Namespace, not on this machine.

### 1. Install the CLIs and log in

On the dispatcher machine, install the [Devbox CLI](https://namespace.so/docs/reference/devbox-cli/installation.md) and [Amp CLI](https://ampcode.com/docs):

```bash wrap theme={null}
curl -fsSL https://get.namespace.so/devbox/install.sh | bash
curl -fsSL https://ampcode.com/install.sh | bash
```

Use Devbox CLI version **0.0.205 or later**. If it is already installed, run `devbox update`.

Log in to the Namespace workspace where you want the orbs to run:

```bash theme={null}
devbox login
```

### 2. Set up the dispatcher

```bash wrap theme={null}
devbox beta amp setup-orb-dispatcher
```

Setup builds and registers an Amp-specific Devbox image, creates a scoped, revokable Namespace API token, and generates an executable `namespace.dispatch.sh`. You do not need to build an image or write a dispatch script yourself.

Setup prints an `amp orb provider` command with the script's full absolute path. Save this command for the next steps. Keep the generated state directory on persistent storage: it contains the Namespace credential and the project snapshot index.

> [!NOTE]
>
> The Namespace token expires after 30 days by default. To choose a longer lifetime when setting up the dispatcher, use `--token-duration`, for example `--token-duration=2160h` for 90 days. The maximum is 365 days.

### 3. Register the provider in Amp

In your Amp workspace, open **Settings → Orbs**, select **Add Orb Provider**, and name it `namespace`.

Copy the provider token. Amp shows it only once. This is a separate credential from the Namespace token created by setup.

### 4. Start the provider

On the dispatcher machine, set the Amp provider token:

```bash wrap theme={null}
export AMP_ORB_PROVIDER_TOKEN="<your Amp provider token>"
```

Run the exact command printed by setup. It has this form, with your generated script's path:

```bash wrap theme={null}
amp orb provider /absolute/path/to/namespace.dispatch.sh
```

Leave this process running so Amp can start, pause, and resume orbs. For an unattended dispatcher, run it under a service manager that restarts it after a reboot and supplies `AMP_ORB_PROVIDER_TOKEN`.

The provider connects out to Amp over HTTPS. You do not need to expose an inbound port.

### 5. Start a thread on Namespace

In Amp's new thread composer, click **Orb**, open the type dropdown, and choose **namespace** under **Self-Hosted**. Select your project and give the agent a task, such as:

```text wrap Agent Prompt theme={null}
Run the test suite and summarize any failures.
```

Amp asks the dispatcher to start a Devbox, checks out your repository, and prepares the project. You can find the orb's Devbox under **Managed Agents** in the [Namespace dashboard](https://cloud.namespace.so/workspace/devboxes).

## How it works

The dispatcher manages Devboxes in response to Amp's lifecycle requests. Each thread uses its own Linux Devbox with the image prepared by setup.

When Amp pauses an orb, Namespace saves its filesystem. Your files and installed software survive, but memory and running processes do not. A later message resumes the same Devbox and reconnects it to Amp.

The dispatcher also supports Amp project snapshots. New threads can fork a saved, prepared filesystem instead of repeating project setup. Keep project-specific dependencies in [`.agents/setup`](https://ampcode.com/docs/orbs/customizing), and use `.agents/resume` to restart services after a pause.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.