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 (/login in an interactive session)
  • Network access to Factory APIs and the relay for your organization's region: relay.factory.ai for non-EU organizations, or relay.eu.factory.ai for EU organizations.
Note

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

Bash
droid daemon --remote-control

If 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.

Note

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

Note

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.

  1. 1
    Open a terminal session that keeps running

    Start a tmux session so the daemon keeps running after you disconnect. You can use screen instead.

    Bash
    tmux new -s droid
  2. 2
    Sign in as the service account

    In the tmux session, paste the service account's API key when prompted. Reading it this way keeps the key out of your shell history.

    Bash
    read -rs FACTORY_API_KEY && export FACTORY_API_KEY
  3. 3
    Register the computer and start the daemon

    Register the computer with a name your team will recognize in the pool table, then start the daemon:

    Bash
    droid computer register build-host-1 --yes
    droid daemon --remote-control

    If the computer is already registered under a personal account, run droid computer remove first. Only one registration is allowed per computer.

    Detach from the session with Ctrl+B, then D. The daemon keeps running. Reattach later with tmux attach -t droid.

  4. 4
    Confirm 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. 1

    Reattach with tmux attach -t droid, and stop the daemon with Ctrl+C, so only one daemon runs.

  2. 2

    In the same session, where FACTORY_API_KEY is still set, save the key to a file only you can read:

    Bash
    mkdir -p ~/.config/droid
    (umask 077 && printf 'FACTORY_API_KEY=%s\n' "$FACTORY_API_KEY" > ~/.config/droid/pool.env)
  3. 3

    Create the service file. If command -v droid prints a different path, use it in ExecStart.

    ~/.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. 4

    Start the service, and let it run while you are logged out:

    Bash
    systemctl --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 --human to see registered computers in a table, followed by any Factory Environments; omit --human for 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 remove to 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