Guides for using iMothership at work

imothership-agent

Run iMothership agent commands on your own computer or a Raspberry Pi. imothership-agent is a small command-line agent: your project sends it coding prompts, git commands and GPIO commands, and it runs them locally and sends the output back.

It's for teams who want their iMothership agents to work on a real machine: a developer laptop with your repositories on it, a build box, or a Raspberry Pi wired up to hardware. The command is imship.

How it works

• Bridge (recommended):imship bridge opens an outbound connection to the iMothership API using a project API key. When an agent in that project sends work, the job arrives over that connection, runs on your machine, and the output streams back. Nothing needs to connect in to your machine.
• Local server:imship engage runs a small HTTP server on 127.0.0.1:4317. This is for setups where iMothership itself runs on the same machine or network.

Jobs come from agents that have the iMothership Agent tool turned on in your project's prompt settings (under Advanced). Each job is one of three kinds: a coding prompt, a git command, or a GPIO command.

Requirements

• Node.js 18 or later.
• A project API key. An organisation admin can create an active key of type Api in the project's API Keys & Webhook Endpoints settings. The secret is only shown once.
• For coding prompts: the coding CLI the agent drives, plus an OPENAI_API_KEY. Run imship codex-install to install the CLI globally; if it isn't installed, the agent fetches it with npm exec when needed.
• For git commands: git installed on the machine.
• For GPIO: Linux with GPIO sysfs at /sys/class/gpio, such as a Raspberry Pi.

Install

npm install -g imothership-agent
imship --version

Background running is handled by PM2, which comes bundled with the package, so there's nothing else to install.

Connect it to your project

1. Save your project API key on the machine. It's stored in ~/.imship/project-keys.json, and list shows keys partly hidden.

   imship project-key add YOUR_PROJECT_API_KEY
   imship project-key list

2. Point the bridge at the iMothership API and start it. Set IMSHIP_BRIDGE_BASE_URL yourself: if it isn't set, the bridge tries http://localhost:8000.

   Bash or zsh:

   export IMSHIP_BRIDGE_BASE_URL='https://api.imothership.com'
   imship bridge

   PowerShell:

   $env:IMSHIP_BRIDGE_BASE_URL = 'https://api.imothership.com'
   imship bridge

3. Check the output. Once it's connected you'll see something like this, and the agent then waits for jobs:

   [imship] bridger connecting to https://api.imothership.com/api/v1/imship/stream
   [imship][bridger] connected to stream

imship bridge runs in the terminal you start it from, so keep that terminal open. If the connection drops, it reconnects on its own, waiting a little longer each time (up to 15 seconds by default).

The bridge uses your key to sign in, and iMothership works out the project from it. Jobs are queued per project, and results can only be sent back for the project the job came from.

Using it from your project

Turn on the iMothership Agent tool for an agent in your project's prompt settings. That agent can then send work to the connected machine:

• Coding prompts: the prompt is run by the coding CLI on your machine, optionally in a given folder, and its output streams back.
• Git commands: the git arguments are run as given, in a chosen folder or the default from IMSHIP_GIT_CWD.
• GPIO commands: list, export, unexport, set the mode of, read and write Raspberry Pi pins.

For example, a git job and a GPIO job sent by the agent look like this:

{"mode":"git","gitArgs":["status","--short"]}
{"mode":"gpio","gpioArgs":["write","17","1"]}

A coding prompt can run for up to 10 minutes on your machine by default. iMothership waits up to 3 minutes for a tool call by default, so keep jobs focused, and make sure the agent is connected before you send work.

Commands

Connect and run

Start the agent and keep it running.

Project keys

Store the project API keys the agent uses. Alias: imship key.

Coding, git and GPIO

Run the same kinds of work yourself from the command line.

Other

Everything else.

Try git and GPIO by hand first to check the machine is set up:

imship git status --short
imship git log --oneline -5

Running on a Raspberry Pi

GPIO commands use Linux GPIO sysfs at /sys/class/gpio. On anything other than Linux, or if that path is missing, GPIO commands stop with a clear error. Writing a value sets the pin to output first.

imship gpio export 17 out
imship gpio write 17 1
imship gpio read 17
imship gpio unexport 17

To keep the background agent running after a reboot:

imship engage
imship save
imship startup

Local server

If iMothership runs on the same machine or network, you can use the local server instead of the bridge. It runs in the background as imship-agent:

imship engage
imship status
imship logs
imship disengage

Once any key is saved, every request to the local server needs a matching key in x-imship-api-key, x-api-key or an Authorization: Bearer header. An optional x-imship-project-id header makes the key match that exact project. GET /health is always open, for health checks.

Configuration

Security

• It runs real work. Coding prompts and git commands run with your user account's access, in the folder the job names. Only run the agent on machines and folders you're happy for your project's agents to work in.
• Outbound only for the bridge. The bridge connects out to iMothership; it doesn't open a port on your machine.
• The local server stays local. It listens on 127.0.0.1 by default and refuses to start on any other address without a key, unless you deliberately override that.
• Keys are checked carefully. Keys are compared in constant time, and a key tied to a project ID only works for that project.
• Protect the key file. Saved keys are stored as plain text in ~/.imship/project-keys.json. Keep that file private, and remove keys you no longer use with imship project-key remove.

Troubleshooting

• "No bridge API key configured": save a key with imship project-key add, or set IMSHIP_BRIDGE_API_KEY.
• The bridge connects to localhost:8000: set IMSHIP_BRIDGE_BASE_URL to https://api.imothership.com.
• "Bridge stream failed (401)": check the project API key is active and copied in full.
• Requests time out in iMothership: check the bridge is running and connected, and that it's using a key for the same project.
• "refusing to start agent with auth disabled": you've set the local server to a non-local address with no key. Save a key, or keep the default 127.0.0.1.
• Unauthorised (401) from the local server: the request's key is missing or doesn't match a saved key.
• GPIO errors: GPIO only works on Linux with /sys/class/gpio available.
• Checking the background agent: use imship status and imship logs.

Connecting an AI assistant instead? See the MCP server guide. To call iMothership from your own code, see the API documentation.

Back to all resources