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
automationmanagecapability, which also covers theautomationreadcapability, and thefactory.read,factory.deploy, andfactory.activateaction grants. See API keys and API overview; - a team id and a project id;
- the
openfactorbinary.
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_01Steps
1. Scaffold the Factory
openfactor factory init ./my-agent
openfactor factory info --directory ./my-agentfactory 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 --jsonDeploy 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 --jsonReplace 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" --jsonA 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. Runfactory get, then resend with the currentversionas--expected-versionand a new--command-key.command_conflict- the--command-keywas already used for a different request. Resend with a new--command-key. Only the same decoded JSON content under the same key replays, returningreplayed: 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 notactive, or changing an archived Factory. Runfactory getand choose a command the state admits instead of retrying.
Other responses:
422- the manifest or request body is invalid. Fix the request and resend.404withagent_not_deployed- the Factory has no deployed revision yet. Runfactory deployfirst.202withapproval_required- a nested Workflow action needs approval. After approval, repeat the same command with the same--command-keyand--expected-version. Whenapproval.factoryCommandCommittedistrue, the Factory state is already saved and only schedule reconciliation is pending.
Next steps
- Factory - the states, revisions, and lifecycle commands
- Workflow and Run lifecycle - how a Factory's Workflow runs
- API overview - authentication, capabilities, and endpoint families