Getting Started
Requirements
- A Namespace account.
- An Amp workspace 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.
Install the CLIs and log in
On the dispatcher machine, install the Devbox CLI and Amp CLI: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:Set up the dispatcher
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.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.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.Start the provider
On the dispatcher machine, set the Amp provider token:Run the exact command printed by setup. It has this form, with your generated script’s path: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.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: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.
Agent Prompt
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, and use .agents/resume to restart services after a pause.