Work with Mecha
Every machine runs Mecha, an AI assistant that works on the machine itself. It writes and runs code, installs packages, serves what it builds and commits to your repositories. Deployport provides the model, so you set up no API key.
Open it
Section titled “Open it”Open the machine and choose Assistant in the row of ways in, or choose Open Mecha at the bottom of the machine’s Chat tab. Mecha opens in a new browser tab, signed in as you. The Chat tab shows the machine’s latest conversation. When you launch a machine, its First prompt step opens the first conversation with the text you give it.
The CLI gives Mecha its first task when you create the machine. --prompt opens the machine’s first conversation with that text once the machine is ready, in up to 255 characters:
deployport machinery create --prompt "build a minimalistic website that says Hi"The console signs you in to Mecha for 12 hours. Its address opens only through the console, so a bookmarked address shows Not found until you open Mecha from the console again.
Opening Mecha needs machinery:BeginAssistantSession on the machine. Mecha runs commands as root on the machine, so this permission is as strong as root access. Removing it from a person ends their open session within about a minute.
What it can do
Section titled “What it can do”Mecha runs as the machine’s login user, deployport, which uses sudo without a password, so it can change anything on the machine. It comes with skills for the work people ask for most:
- github clones, pushes and creates repositories through your GitHub connection, with no login step.
- receiving-traffic builds a page or an app and serves it on the machine’s address.
- node-and-js-frameworks installs Node and gets dev servers such as Next.js and Vite working behind the machine’s address.
- schedule does work later or on a schedule, and starts a new conversation for each run.
- previous-conversations finds an earlier conversation and picks it up.
- mecha-hooks explains how to change Mecha’s behaviour with hooks.
Work it does for you lands in ~/projects, one directory per project. Ask for a page or for a repository to be cloned and that is where it goes. Your own files, such as ~/.config/mecha and your shell profile, stay in your home directory, so a project that cleans up after itself cannot take them.
The machine keeps running while it works
Section titled “The machine keeps running while it works”A machine does not stop itself while Mecha is working on a task. The machine’s Auto-stop field reads Waiting for the AI harness to finish a task until the task ends, and then the usual idle rules apply again. Mecha waiting for your reply is not working, so an open conversation does not keep the machine running on its own. Let a machine stop itself covers the idle rules.
Make it yours
Section titled “Make it yours”- Standing instructions:
~/.config/mecha/AGENTS.mdapplies to every conversation. Edit it in Mecha with Edit User AGENTS.md. Mecha also reads anAGENTS.mdorCLAUDE.mdin the project it works in. - Your own skills: put a skill at
~/.config/mecha/<skill>/SKILL.md. A skill there replaces one Machinery ships with the same name. - Hooks: an executable at
~/.config/mecha/hooks/<name>runs at a point in a conversation, such as a new message or the end of a turn. Ask Mecha about hooks, and it explains them with its mecha-hooks skill.
Machinery manages /etc/mecha/ and the new-conversation hook, and rewrites them, so changes there are replaced.
Conversations survive stops
Section titled “Conversations survive stops”Conversations are stored on the machine’s disk, so they survive a stop, a start and a restart, and a snapshot keeps them. A task that is running when the machine stops or Mecha restarts does not pick up where it left off, so ask again.
Commits it makes
Section titled “Commits it makes”Mecha commits as the person who created the machine, and it adds a co-author line to the commits it makes. Push to GitHub explains the line and how to turn it off.
Check it
Section titled “Check it”If everything worked, Mecha opens signed in as you and the conversation starts with the first prompt you gave at launch.
If it does not open, Assistant failures names the cause.