Droid Computers

Droid Computers are persistent compute environments hosted and managed by Factory that Droid can connect to and work on across sessions. They retain state: installed packages, files, running services, and configuration all persist between sessions.

Factory provisions and maintains the underlying cloud environment. To work on a computer you already manage, use Remote Control instead.

Using Droid Computers in sessions

Factory App

In the new session modal, select the Computer tab, pick an active Droid Computer, set a working directory (for example, /home/factory-user/projects/my-app), and start your session.

Connection status (connecting / connected / error) is shown in real time.

Managing Droid Computers

From Settings → Droid Computers, you can:

• Browse available Droid Computers
• Rename a Droid Computer
• Delete a Droid Computer
• Open the detail page for status and connection information

Use your own computer

Remote Control connects a computer you already manage, such as a VPS, cloud VM, workstation, or on-prem server. It is a separate option from Factory-managed Droid Computers.

Create a Droid Computer

The fastest way to get started is to create a Droid Computer directly from the Factory App.

1. 1
   Navigate to Settings → Droid Computers.
2. 2
   Click Create.
3. 3
   In the creation wizard, give your Droid Computer a name. Review the owner and available provider options; eligible managers and owners can select a service account as the owner.
4. 4
   When Environments are enabled for your organization, choose a Ready Environment or start from a clean computer. The Environment selector is not shown when you add computers to a delegation pool.
5. 5
   Review the repositories and dependency setup options, then confirm Create. Repositories already included in an Environment do not need to be selected again; you can add more for this computer.

A computer created from an Environment starts from its successful snapshot and retains its own subsequent state. Later Environment rebuilds do not update an existing computer. See Run Droids on an Environment for this option.

Factory provisions the computer using the chosen provider and source. Provisioning progress is tracked live in the UI through the following steps:

1. 1
   Creating Droid Computer: allocating the cloud Droid Computer
2. 2
   Setting up user: creating the factory-user account with sudo access
3. 3
   Configuring environment: writing environment config, SSH keys, and service files
4. 4
   Installing Droid: downloading and installing the Droid binary
5. 5
   Starting services: launching the SSH and Droid daemon services

Once provisioning completes, the Droid Computer status changes to Active and it becomes available for use in sessions. Platform-managed Droid Computers auto-pause when idle and auto-resume when a new session targets them. They also expose provisioning details, resource metrics, and remote update flows.

Create a delegation computer pool

Delegations with Persistent compute run on a pool of computers instead of a fresh computer for each request. The pool is every active computer owned by the agent profile's service account. To add a computer to the pool, make the service account its owner. You can mix Droid Computers with your own computers connected through Remote Control in the same pool.

Before you start

• You have the Manager or Owner role.
• Managed computers are available for your organization.
• The Apps agent profile has an active service account selected in its Identity step.
• The service account can access the repositories the work needs. See repository access for the service account.

Add managed computers to the pool

1. 1
   Open the Compute step

   Open Settings → Delegations. Under Agent Profiles, select Edit on Apps, then open the Compute step and set the machine type to Persistent.

2. 2
   Choose how many computers to create

   Select Add Managed Computer. In the New managed computers wizard, enter a Quantity from 1 to 20. Factory names the computers automatically, such as delegation-machine-1 and delegation-machine-2, using the lowest free numbers.

   The service account is always the owner, and pool computers always start from a clean computer, so the wizard does not ask for an owner, a name, or an Environment. If your organization has more than one compute provider, choose one here.

3. 3
   Choose repositories

   Select the repositories every computer in this batch should clone. Under Set up repositories, choose Set up automatically (recommended) to install dependencies after cloning, or Skip for now. Then select Create computer.

   For GitHub, pick repositories covered by one installation of your organization's Factory GitHub App.

4. 4
   Wait for the computers to become active

   The wizard closes and provisioning continues in the background. The pool table lists each computer with the type Managed by Factory and its status. Computers show Active when they are ready to take work.

5. 5
   Set the parallel worker limit and save

   Set Per machine parallel worker limit, then select Finish. See size the pool. Saving a Persistent profile requires at least one computer in the pool.

To add computers later, select Add Managed Computer again. You can also create a computer from Settings → Droid Computers and choose the service account as its Owner. That flow lets you name the computer and start it from an Environment.

If a batch fails partway through, Factory keeps the computers it already created and reports how many it made. Check the pool table before you create the rest, so you do not create more than you need.

Size the pool

Each computer runs up to Per machine parallel worker limit delegated sessions at once. The limit defaults to 3 and can be set from 1 to 50; Factory recommends 3 to 5. It applies to every computer in the pool.

The pool's capacity is the number of computers multiplied by this limit. A session holds its slot while it runs and for 30 minutes after it goes idle, so follow-up messages can continue on the same computer. Parallel sessions share the computer's CPU, memory, and disk, so raise the limit only on computers with room to spare.

How Factory uses the pool

For each new shared delegation, Factory picks the active pool computer with the fewest sessions that is still under the limit. Paused Droid Computers resume automatically when they are picked. If every computer is at its limit, the request waits and starts when a slot frees up. Add computers or raise the limit to shorten waits.

Sessions on the same computer start in its home directory or first cloned repository. Droid is instructed to work in its own git worktree, so parallel sessions do not edit the same checkout.

CLI commands

General

Your own computer

To register and connect a computer you manage, see Remote Control.

SSH options

The ssh subcommand supports the following flags:

• --proxy: Run as a stdio proxy (for use as a ProxyCommand)
• --port <port>: Target port on the remote machine (default: 22)
• --debug: Enable verbose connection logging

Port forwarding

droid computer port-forward <name> <mappings...> forwards local TCP ports to a Droid Computer over the same relay tunnel used by droid computer ssh -- no direct port exposure is required. Managed Droid Computers are woken automatically before the connection is established.

Mappings can be passed multiple at a time in one command:

• LOCAL:REMOTE -- bind LOCAL locally and forward to REMOTE (e.g. 8080:80)
• REMOTE -- use the same port on both sides (e.g. 5432)
• :REMOTE -- pick a random free local port (e.g. :9000)

# Forward local 8080 to remote 80, and local 5432 to remote 5432
droid computer port-forward mycomputer 8080:80 5432

The port-forward subcommand supports the following flags:

• --address <addr> -- Local address to bind (default: 127.0.0.1)
• --debug -- Enable debug output

Only TCP is supported.

Monitoring

Click on any Droid Computer in Settings → Droid Computers to open its detail page. For platform-managed Droid Computers, the detail page shows live resource metrics:

CPU usage

Percentage utilization over time.

Memory usage

Used vs. total memory.

Disk usage

Used vs. total disk space.

The detail page also shows the current daemon version and connection status. Possible Droid Computer statuses are:

Provisioning

Initial setup in progress.

Active

Ready for sessions.

Error

Provisioning or runtime failure.

Updating the daemon

The Droid Computer detail page displays the running daemon version alongside the latest available version. When an update is available, an Update button appears. Clicking it triggers a remote update: the daemon downloads the new binary, restarts, and reconnects automatically.

Git credentials

If you have a personal GitHub integration with Factory, credentials are added automatically for authenticated repository access. When you add new GitHub App installations or change repository access, credentials are refreshed automatically on the next session connection.

Factory does not manage commit-signing keys. To push signed commits, for example to a repository that rejects unsigned commits, see Sign commits on managed computers.

SSH & IDE integration

droid computer ssh <name> establishes a secure WebSocket tunnel through the daemon. No direct SSH port exposure is required. Factory generates and manages a dedicated Ed25519 SSH key pair (stored in ~/.factory/.ssh/), separate from your personal SSH keys. The public key is injected on each connection for passwordless authentication.

VS Code Remote-SSH

You can use droid computer ssh as a ProxyCommand for VS Code Remote-SSH. Add the following to your ~/.ssh/config:

Host factory-*
  ProxyCommand droid computer ssh %h --proxy
  User factory-user
  StrictHostKeyChecking accept-new
  UserKnownHostsFile ~/.factory/.ssh/known_hosts
  IdentityFile ~/.factory/.ssh/id_ed25519
  IdentitiesOnly yes

The wildcard factory-* host applies to every Droid Computer, and %h passes the host name through to the CLI, so you connect to factory-<computer-name> (for example, factory-mycomputer) without adding a stanza per computer. Host keys are recorded on first connect (StrictHostKeyChecking accept-new) in a dedicated ~/.factory/.ssh/known_hosts file, so a changed key surfaces an SSH warning instead of being accepted silently.

This lets you open a full VS Code remote session on your Droid Computer.

Security

• Firewall: Platform-managed Droid Computers use iptables rules to restrict inbound traffic to the daemon port only; all other ports are blocked by default. Note that factory-user has passwordless sudo access and could modify these rules.
• SSH hardening: Root login and password authentication are disabled.
• Git credentials: Configured automatically per-user for authenticated repository access on platform-managed Droid Computers.