Skip to main content
Your agent never logs in. It reuses the difyctl session on the machine where it runs. How you get it there depends on the machine:
  • Your own machine: sign in 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 account the agent should act as. The agent inherits everything that account can reach. On a self-hosted deployment, 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. For the full walkthrough, see Authenticate. Confirm it landed: 
difyctl auth whoami

<your-email> (<your-name>)

​
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.
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.
Last modified on June 25, 2026