Skip to main content
Your agent never logs in. It reuses the difyctl session on the machine where it runs, acting as whoever signed in: an account user, or an external SSO user limited to their permitted apps. How you get a session there depends on the machine:
  • Your own machine: sign in (account or SSO) and you’re set.
  • A server or VM you can log into: sign in on it (Option 1).
  • A container, CI runner, or prebaked image: copy a session in (Option 2).

​
Option 1: Sign In on the Machine

Sign in on the target machine as the identity the agent should act as. The agent inherits everything that identity can reach: an account user’s workspace apps, or the apps an external SSO user is permitted to run. Use the console API URL for --host. Pass --no-browser when the machine has no browser: 
difyctl auth login --host https://dify.example.com --no-browser
difyctl prints a one-time code and a verification URL. Open the URL on any device, sign in, and enter the code. The session is written to the machine the moment you approve. Confirm it landed: 
difyctl auth whoami

<your-email> (<your-name>)
An external SSO user sees <your-email> (external SSO, issuer: <your-identity-provider>) instead.

​
Option 2: Copy a Session You Already Have

Use this when you can’t sign in on the target itself, like a prebaked image or an ephemeral container.
1

Sign in on a machine without an OS keychain

Use a headless Linux server or a container. Without a keychain, difyctl saves the token to tokens.yml in the config directory, making the entire directory portable.Before copying, confirm tokens.yml exists in the config directory (~/.config/difyctl by default). If it’s missing, a keychain captured the token instead, and there’s no supported way to export it. Sign in directly on the target with Option 1.
2

Copy the config directory to the target

After copying, point difyctl at it with DIFY_CONFIG_DIR. For a container, mount the directory at runtime instead of baking it into the image:
docker run \
  -v /path/to/difyctl-config:/config:ro \
  -e DIFY_CONFIG_DIR=/config \
  your-agent-image
tokens.yml is a live credential. Keep its 0600 permissions and keep it out of images and version control. The mount is read-only because an agent that only runs apps never writes to the config directory.

​
When the Session Expires

A server-expired or revoked session surfaces as exit code 4 with error.code auth_expired. The agent can’t recover on its own: a new session takes a person approving the sign-in, the same one-time-code step as Option 1. So it should stop and surface the failure for a human to sign in again, not retry. See Handle Errors and Retries for how to branch on it. To revoke a session you suspect is compromised, run auth devices revoke from any signed-in machine.