Run agents on your machine

An agent can run on a Linux machine you own instead of an Auteryn cloud sandbox. Its shell, files and git then work in a folder on that machine, usually a repository you have already checked out, with the tools you have installed.

Available on: Internal agents on paid plans. Pro includes one machine, Business five, and Enterprise as many as your agreement sets. Reading the web through your machine needs Business or Enterprise.

What it’s for

The agent works in your repository, with your runtimes and your build cache. Files stay on your disk between runs. There are no snapshots, so every change is real.
Web requests leave from your machine’s internet connection, so sites see your IP address. Your local network is blocked unless you allow a range (see Local network).
Runs on your machine use none of your plan’s computer hours. See Pricing & Credits.

Nothing connects in to your machine. A small program, the runner, dials out to Auteryn over HTTPS on port 443. You don’t open any ports, and you don’t need port forwarding or a static IP.

Before you start

You need:

Ubuntu 22.04 or later, Debian 12 or later, or a distribution built on one of them
An amd64 or arm64 processor
An account that can run sudo
systemd running. WSL without systemd and containers aren’t supported.
Outbound HTTPS (port 443)
About 600 MB of free disk space
An owner or admin role in your organization, to add the machine in the Console

The machine then belongs to the person who added it (see Who can use your machine).

Install the runner

In the Console, open the agent, go to Computer and choose Your machine. Select Add a machine, give it a name, enter the Workspace path (the folder the agent should work in, usually a repository you’ve already checked out) and choose an access mode. Choose Confined unless the agent needs your own git and CLI sign-ins (see Choose an access mode).
On the machine, open a terminal.
Copy the command from the Console and run it. It looks like this:
Terminal window
```
f=$(mktemp) && curl -fsSL https://get.auteryn.ai/runner/v2 -o "$f" \
  && echo "<checksum>  $f" | sha256sum -c - \
  && printf '%s' '<install code>' | sudo bash "$f" --token-stdin --workspace '/home/ana/projects/myrepo' --confined \
     --device-url https://api.devices.auteryn.ai \
  ; rm -f "$f"
```
If your network needs a proxy, add --proxy http://proxy.example:3128 before you run it.

The command includes the access mode you chose (--confined or --full-account) and checks the installer against a checksum before running it. The install code goes in on standard input, so it never appears in the machine’s list of running processes. The code works once, and the Console shows how long it is valid. If it runs out, select Get a new command.
The installer checks the machine and marks each item ✓ or ✗. If a check fails, it doesn’t change anything and says what to fix. It then adds the Auteryn package source, installs the signed auteryn-runner package and waits up to a minute for the machine to connect.
The Console shows the machine as connected, with its hostname, operating system, access mode and runner version. Select Use for this agent.

The Workspace path you entered becomes the agent’s workspace. The installer refuses /, /home, your whole home folder, a folder inside .ssh or containing one, and system folders.

Choose an access mode

The access mode decides which account the agent runs as. You choose it when you add the machine, as Confined (recommended) or As the installing user. The Console then shows it on every machine as Confined or Full account access.

	Confined (recommended)	Full account access
Runs as	A separate `auteryn-runner` account	Your own account
Can change	Only the workspace folder	Anything your account can change
Can read	The system and the workspace. Your home folder, SSH keys and cloud credentials are hidden.	Everything your account can read, including `~/.ssh` and stored tokens
Your git and CLI sign-ins	Not available	Available, so the agent can push with your git setup
Can become root	No	No

Choose Full account access only for a machine or an account with nothing on it that the agent shouldn’t see. To change the mode later, remove the machine and add it again with the other mode.

On your machine

The agent has the same shell, file and git access it has in a cloud sandbox, in your workspace folder.

Limits

The runner keeps the agent from taking over the machine:

It runs at a lower priority than your own programs and can use at most three quarters of the machine’s memory.
A single command stops after 30 minutes, and at most four run at once.
It can’t use sudo or become root, in either access mode.

Local network

Your local network is blocked by default: the agent can’t connect to your router, a NAS or other machines on your network. The blocked ranges are 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 169.254.0.0/16, 100.64.0.0/10 (which includes Tailscale addresses), fc00::/7 and fe80::/10. Connections to the machine itself (127.0.0.1) still work, so the agent can use a dev server it starts.

To allow a range, such as an internal package registry or a company proxy, add it to /etc/auteryn/runner.env (separate several with spaces or commas):

AUTERYN_ALLOW_NETS=10.20.0.0/16

Then apply it:

sudo auteryn-runner reconfigure --restart

This ends a run in progress. Terminals already open keep the old rule until they restart.

Your home folder and your repository

Auteryn doesn’t write to your home folder. What the runner and its agents set up is stored in /var/lib/auteryn/state: the Git, Google Cloud and Azure sign-ins an agent uses, its task files, its memory and its terminal history. Task files and terminal history nobody has used for 7 days are deleted. Your own ~/.gitconfig, gcloud and az setups stay as they are.

In your workspace, the runner adds three links into that folder (.tasks, .memory and .terminal_history) and lists them in .git/info/exclude, so git ignores them.

Commands the agent runs can still change files. In Confined mode that means the workspace folder. In Full account access mode it means anything your account can change.

When you stop using the machine for an agent, move it to another agent or remove it, Auteryn removes what agents left there: their session settings, their Git, Google Cloud and Azure credentials, and their task files, memory and terminal history. Nothing else on the machine changes. If the machine is offline at that moment, it’s cleaned the next time it connects.

If your machine is offline

For each agent, choose what happens if the machine can’t be reached (If the machine is offline):

Use a cloud sandbox: the run moves to a cloud sandbox. The workspace says so and names the machine (“Running in the cloud: ana-thinkpad was unreachable”), with a button to retry on the machine. Your machine’s files aren’t available in the cloud sandbox.
Don’t run: the run stops and tells you the machine is offline and when it was last seen.

What leaves your machine

Command output and file contents the agent reads are sent to the model and kept in the chat history.
Screenshots the agent takes of the browser are sent to the model.
Files the agent exports to you are stored by Auteryn for 60 days.

Who can use your machine

A machine belongs to the person who added it. That person chooses who can have agents work on it, in Who can use this machine:

Setting	Who can run an agent on the machine
Only me (default)	Only you
Me and admins	You and your organization’s owners and admins
Everyone in the org	Anyone in your organization who can use the agent, including runs started with an API key

Only the person who added the machine can assign it to an agent, move it to another agent, give other agents read access, change who can use it, rename it or allow the browser on it. That person, and owners and admins, can stop an agent using it or remove it. Other members see its name, status and runner version.

A Loop runs as the person who created it. It can use your machine only if that person can.
Guests and customers never run on your machine, and customer-facing agents can’t use one.
If someone who isn’t allowed runs the agent, the run stops and says whose machine it is. It doesn’t move to the cloud.

Let other agents read it

One agent has full access to a machine. You can also let other agents read its workspace, such as a reviewer reading the code another agent is changing.

In the Console, on the machine, select Add a read-only agent. Or, in the other agent’s Computer section, choose Read another machine.
A read-only agent can list, read and search files, and read git status, diffs and history. It can’t run commands, change files, open a terminal or use the browser.
An agent reads at most one machine, and an agent that runs on a machine can’t also read another one.
A read-only agent never moves to the cloud. If the machine is offline, the run says so.
Another agent may be editing, so files can change between reads.

Add the browser

The agent can use a real browser on your machine. It uses your machine’s network, and it can act inside any site that browser is signed in to.

Install the browser add-on on the machine (about a 300 MB download; it needs about 1 GB of free memory):
Terminal window
```
sudo apt update && sudo apt install -y auteryn-runner-chromium
```
On the agent, turn on Let my agent use a browser on my machine. The first time, the person who added the machine confirms it for that machine. Until they do, nobody can turn it on there.

Even on a machine shared with everyone, only owners and admins can run an agent that uses its browser. If Google Chrome is installed on the machine, the agent uses it automatically.

Read the web through your machine

On Business and Enterprise, an agent can read web pages through your machine’s connection, from your IP address. This helps with sites that turn away cloud servers.

Turn on Read the web from my machine on the agent. Web searches still run from Auteryn.
In the chat, a read that went through your machine is marked via your machine, and one that fell back to the cloud while the machine was offline is marked via cloud.
With Only read the web through my machine, a read fails when the machine is offline instead of using the cloud.
Only your team’s runs of Internal agents read through your machine. Guest and customer conversations never do.

Update the runner

The Console shows each machine’s runner version. When a newer one is published, it shows Update available with the command to run on the machine:

sudo apt-get update && sudo apt-get install --only-upgrade -y auteryn-runner auteryn-runner-chromium

Or run sudo auteryn-runner update on the machine. The runner restarts itself when no run is active, shows as Updating… and reconnects in about a minute. Add --now to restart it at once.

Update required means the runner is older than agents can use. Agents can’t use the machine until you update it. Until then, a run follows the machine’s offline setting: it moves to the cloud (“Running in the cloud: ana-thinkpad needs a runner update”) or stops.

On the machine, auteryn-runner status shows the installed version and whether an update is available.

Reinstall the runner

Reinstall when the Console shows Needs repair, or when the machine won’t connect. The machine keeps its name and the agent using it, and gets new credentials. To move the agent to another folder, remove the machine and add it again.

In the Console, open the machine’s menu and select Reinstall.
Run the command it shows on the machine, from the folder the agent should work in.

If you install on a computer that is already connected as another machine, the Console offers Replace that machine, which does the same.

Remove the machine

To remove the runner from the machine, run:

sudo apt purge auteryn-runner auteryn-runner-chromium

This tells Auteryn the machine is gone. The Console stops listing it, and it no longer counts toward your plan. The command also removes the runner’s account (in Confined mode) and its access to your workspace folder, and the links it added to your repository. Your workspace files stay. sudo auteryn-runner uninstall does the same.

You can also select Remove on the machine in the Console. That is permanent: the machine disconnects, and any agent using it switches to a cloud sandbox. Run the command above to take the runner off the machine too.

To take the machine offline for a while instead, run sudo auteryn-runner pause, and sudo auteryn-runner resume to bring it back.

Troubleshooting

The Console shows each machine’s status:

Status	What it means	What to do
Waiting	The install command hasn’t run yet.	Run it on the machine.
Command expired	The install code ran out before it was used.	Select Get a new command.
Not connected yet	The runner is installed but hasn’t connected.	Check outbound HTTPS (port 443), then run `sudo auteryn-runner doctor`.
Reconnecting…	The connection dropped.	Wait. It usually comes back within a minute.
Offline	Agents can’t reach the machine.	Check that it’s on and online, then run `auteryn-runner status`.
Needs repair	Agents can’t use the machine until the runner is reinstalled.	Reinstall the runner.
Updating…	The runner is restarting after an update.	Wait about a minute.
Update required	The runner is older than agents can use.	Update the runner.

On the machine:

auteryn-runner status          # what it's doing, its version and updates
sudo auteryn-runner doctor     # check this machine and the runner
auteryn-runner logs -f         # follow its log, with secrets masked

Messages you may see while installing:

“This install code expired. Get a new one in the console.” Select Get a new command and run the new command.
A web page instead of the package list. A captive portal or a proxy is in the way. Sign in to the network, or add --proxy <url> to the command.
“… cannot be the workspace.” The Workspace path is a folder the installer refuses. Remove the machine and add it again with the project folder the agent should work in.