Deploy and activate a Factory

Scaffold a Factory from a local directory, deploy its manifest, activate the revision, and read its state.

A local Factory directory becomes an immutable deployed revision. Activating that revision makes it the active revision the Factory runs. This guide takes you from a directory to an active revision with the command-line interface.

Before you start

You need:

  • a personal API key with the automation manage capability, which also covers the automation read capability, and the factory.read, factory.deploy, and factory.activate action grants. See API keys and API overview;
  • a team id and a project id;
  • the openfactor binary.

Authenticate before the first command. openfactor auth login approves the team in the browser and stores that team's credential in the operating-system keyring, which is the credential the team-scoped commands below read. Confirm the active key with openfactor auth status.

openfactor auth import --token-stdin stores a default credential for commands that name no team. It does not store a team credential. When no team credential is stored for the team and no --credential-file is passed, a team-scoped command fails with No credential is stored for team, even after a successful import. To run a team-scoped command without a browser login, pass a team API key as a mode-0600 file with --credential-file.

The CLI reads only a stored credential, or a --credential-file passed to one invocation. It never reads an API_KEY environment variable.

Set the ids once and pass them as flags:

export TEAM_ID=team_01
export PROJECT_ID=project_01

Steps

1. Scaffold the Factory

openfactor factory init ./my-agent
openfactor factory info --directory ./my-agent

factory init writes the blank-assistant template, which is the only template. factory info lists the authored slots and any diagnostics.

2. Deploy a draft revision

openfactor factory deploy --directory ./my-agent \
  --team-id "$TEAM_ID" --project-id "$PROJECT_ID" \
  --command-key deploy-1 --expected-version null --json

Deploy builds the directory, sends the compiled manifest, and creates an immutable revision. It leaves the Factory in draft. Use null for --expected-version on the first deploy. Read factory.version from the response for the next command.

Deploying another revision preserves an existing active revision.

3. Activate the revision

openfactor factory activate --team-id "$TEAM_ID" \
  --project-id "$PROJECT_ID" --command-key activate-1 \
  --expected-version 1 --json

Replace 1 with the version from the deploy response. Activation makes the deployed revision the active one. A paused Factory stays paused after activation until factory resume admits the revision.

4. Read the Factory

openfactor factory get --team-id "$TEAM_ID" \
  --project-id "$PROJECT_ID" --json
openfactor factory revisions list --team-id "$TEAM_ID" \
  --project-id "$PROJECT_ID" --json

A Factory is in one of four states: draft, active, paused, or archived. After activation, the state is active, and the response's activeRevision field names the revision the Factory runs.

Errors and retries

Every 409 response carries an error code, and each code has its own recovery:

  • version_conflict - the Factory changed after your read. Run factory get, then resend with the current version as --expected-version and a new --command-key.
  • command_conflict - the --command-key was already used for a different request. Resend with a new --command-key. Only the same decoded JSON content under the same key replays, returning replayed: true; JSON whitespace does not change that identity.
  • invalid_transition - the current state does not admit the command, such as activating the revision that is already active, pausing a Factory that is not active, or changing an archived Factory. Run factory get and choose a command the state admits instead of retrying.

Other responses:

  • 422 - the manifest or request body is invalid. Fix the request and resend.
  • 404 with agent_not_deployed - the Factory has no deployed revision yet. Run factory deploy first.
  • 202 with approval_required - a nested Workflow action needs approval. After approval, repeat the same command with the same --command-key and --expected-version. When approval.factoryCommandCommitted is true, the Factory state is already saved and only schedule reconciliation is pending.

Next steps