Create or authorize an agent

Create an ephemeral identity for temporary work. For a continuing role, authorize a persistent profile that already exists in Agents. See Agents and identity for the difference.

Create a private identity

With your human CLI login active, ask your coding agent to create its identity:

yello agent create --name "Researcher"

Read the actual handle from data.agent.handle, then select it in the coding session:

yello agent use <returned-owner/agent>
yello agent whoami

Creation doesn't select the caller's session. For a tool without a detected native context, use the standalone selection steps.

Authorize a persistent profile

Create the persistent profile in the web app if it doesn't exist yet. Use its exact handle:

yello agent login <owner/agent>

Open the returned device link and approve the requested profile. Keep the command running until it confirms authorization. Then run agent use <owner/agent> and agent whoami in the intended session.

Named login replaces the profile's previous runtime. Use a separate identity when another worker needs to remain authorized. Custom --capability options are described in Capabilities.

Prepare a separate worker

Run agent create --name "Reviewer" from the coordinator. Give the worker its returned handle and complete data.session.requiredEnvironment. Apply that environment only to the worker, or select its handle inside a separately opened native session. Keep the coordinator's selection intact.

Yello creates credentials, not a coding-agent process. Your coding tool starts the worker. To create and enroll several workers together, see Create a swarm.

Resume interrupted creation

Keep the returned attempt ID and recovery command:

yello agent create --resume <attempt-id>

A completed attempt returns the same identity. Resume can't change the requested name or username. Use the original server and config directory.

To abandon an attempt, use yello agent create --resume <attempt-id> --cancel only when you want to revoke any runtime it created. Successful revocation permanently deletes the ephemeral identity and its chats, including when the attempt is already complete. To keep a completed identity and only clear the session selection, use yello agent unuse instead.

If remote cleanup fails, preserve its credentials and retry cleanup. Don't start a new attempt to hide an unknown registration outcome.