Remote Control
Connect your computer so Droid can work on it from the web or other devices.
Remote Control connects your Linux, macOS, or Windows computer so Droid can work on it from the web or other devices. Use an environment you already manage, such as a VPS, cloud VM, workstation, or on-prem server. Droid uses the development setup and git credentials already configured on that computer.
Factory does not provision or maintain your computer. For compute hosted and managed by Factory, use Droid Computers. For sandboxes that Factory provisions on demand inside your own infrastructure, see OpenCompute.
Before you start
Make sure you have:
- A computer running Linux, macOS, or Windows
- The Droid CLI installed on that computer
- Authenticated with Factory (
/loginin an interactive session) - Network access to Factory APIs and the relay for your organization's region:
relay.factory.aifor non-EU organizations, orrelay.eu.factory.aifor EU organizations.
No inbound ports need to be opened. Your computer connects through Factory's relay service when you start the daemon with --remote-control (alias: --remote-access).
Connect with the Factory App
The Factory App registers your computer automatically using your system's hostname. Open Settings → Droid Computers and switch on Remote Control to make it reachable from other devices through Factory's relay. The connection remains active while the Factory App is running.
Connect with the CLI
droid daemon --remote-controlIf the computer is not registered, this prompts you for a name and registers it automatically.
To register manually first, run droid computer register [name], then start droid daemon --remote-control to connect through Factory's relay service.
Only one registration is allowed per computer at a time. Run droid computer remove first, or delete the computer through the settings page, if you need to re-register.
Add your computers to a delegation pool
Dynamic compute is the recommended option for delegations. It gives each delegation its own computer built from an Environment, with no pool to size or maintain. Connect your own computers to a pool only when the work needs your network, hardware, or toolchains. See configure delegated sessions.
Delegations with Persistent compute run on a pool of computers owned by the agent profile's service account. Connect your own computers to that pool when delegated work needs your network, hardware, or toolchains. A pool can mix these computers with Factory-managed Droid Computers.
A computer joins the pool when the service account owns it. The agent profile has no button for this. Instead, you register the computer and run its daemon while signed in as the service account with its Factory API key. When FACTORY_API_KEY is set, the Droid CLI uses that key even if someone is also logged in on the computer.
Before you start
- You have the Manager or Owner role.
- Your organization allows Remote Control. The per-member exception for that setting does not apply to service accounts.
- The agent profile, such as Org Default, uses Persistent compute, and its service account is active. See configure delegated sessions.
- You have an API key for that service account. Generate one from the API Keys section of the agent profile editor and store it securely; the key is shown only once. See service accounts.
- Each computer meets the requirements in before you start and has the Droid CLI installed for the user account that will run delegated work.
Register each computer as the service account
Run these steps on each computer, as the user account that will run delegated work.
- 1Open a terminal session that keeps running
Start a
tmuxsession so the daemon keeps running after you disconnect. You can usescreeninstead.Bashtmux new -s droid - 2Sign in as the service account
In the
tmuxsession, paste the service account's API key when prompted. Reading it this way keeps the key out of your shell history.Bashread -rs FACTORY_API_KEY && export FACTORY_API_KEY - 3Register the computer and start the daemon
Register the computer with a name your team will recognize in the pool table, then start the daemon:
Bashdroid computer register build-host-1 --yes droid daemon --remote-controlIf the computer is already registered under a personal account, run
droid computer removefirst. Only one registration is allowed per computer.Detach from the session with
Ctrl+B, thenD. The daemon keeps running. Reattach later withtmux attach -t droid. - 4Confirm the computer is in the pool
In the agent profile's Computers section, the computer appears in the pool table with the type Remote Control and status Active.
Keep the daemon running after a reboot
A daemon started in tmux stops when the computer restarts. On Linux, you can run it as a user-level systemd service instead, so it starts at boot and restarts if it stops. On macOS, use a launchd agent; on Windows, use Task Scheduler.
- 1
Reattach with
tmux attach -t droid, and stop the daemon withCtrl+C, so only one daemon runs. - 2
In the same session, where
FACTORY_API_KEYis still set, save the key to a file only you can read:Bashmkdir -p ~/.config/droid (umask 077 && printf 'FACTORY_API_KEY=%s\n' "$FACTORY_API_KEY" > ~/.config/droid/pool.env) - 3
Create the service file. If
command -v droidprints a different path, use it inExecStart.~/.config/systemd/user/droid-remote-control.service[Unit] Description=Droid Remote Control daemon [Service] EnvironmentFile=%h/.config/droid/pool.env ExecStart=%h/.local/bin/droid daemon --remote-control Restart=always [Install] WantedBy=default.target - 4
Start the service, and let it run while you are logged out:
Bashsystemctl --user daemon-reload systemctl --user enable --now droid-remote-control sudo loginctl enable-linger "$USER"
Prepare the computer for delegated work
Delegated sessions run unattended, often several at once, so set up each computer before it takes work:
- Git credentials: configure credentials on the computer that can clone and push to every repository delegated work needs. Remote Control uses the computer's existing git configuration.
- Toolchains: install the languages, package managers, and CLIs the work uses, for the user account that runs the daemon.
- Capacity: each computer runs up to the agent profile's Per machine parallel worker limit sessions at once, 3 by default. A session holds its slot while it runs and for 30 minutes after it goes idle. Size CPU, memory, and disk for that many sessions. See size the pool.
- Updates: update the Droid CLI on the computer, then restart the daemon. With the systemd service, run
systemctl --user restart droid-remote-control.
Factory skips a Remote Control computer whose daemon is offline and never wakes it. If every computer is busy, new requests wait for a free slot. Keep enough computers online for your team's load.
Troubleshoot pool computers
Troubleshooting availability
Managing and updating your computer
- Use
droid computer list --humanto see registered computers in a table, followed by any Factory Environments; omit--humanfor JSON - Use
droid computer ssh <name>to open an SSH session to a registered computer - Use
droid computer port-forward <name> <mappings...>to forward local TCP ports to a registered computer over the relay - Use
droid computer removeto unregister the current computer and clean up local config - Update the Droid CLI manually on the computer, then restart the daemon process
For example, droid computer port-forward workstation 8080:80 5432 forwards local port 8080 to remote port 80 and local port 5432 to remote port 5432.
Remote Control uses whatever git credentials are already configured on your computer.
Security and networking notes
- No inbound ports: Your computer routes traffic through Factory's relay service, so no public ports are exposed
- Credentials: Factory does not manage git credentials on your computer; its existing git configuration is used
- Ownership: You are responsible for hardening and maintaining the underlying computer