> ## Documentation Index
> Fetch the complete documentation index at: https://dify-6c0370d8-docs-new-agent-experience.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Authenticate Where Your Agent Runs

> Put a difyctl session on the server or container where your agent runs, so it can call Dify apps unattended

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](/en/cli/authenticate) 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.

For Dify Cloud, use `https://cloud.dify.ai` for `--host`; on a self-hosted deployment, use the [console API URL](/en/self-host/deploy/configuration/environments#console_api_url). Pass `--no-browser` when the machine has no browser:

```bash theme={null}
difyctl auth login --host https://cloud.dify.ai --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](/en/cli/authenticate#sign-in).

Confirm it landed:

```bash theme={null}
difyctl auth whoami
```

```text theme={null}
<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.

<Steps>
  <Step title="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](/en/cli/authenticate#where-your-token-lives), 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](#option-1-sign-in-on-the-machine).
  </Step>

  <Step title="Copy the config directory to the target">
    After copying, point `difyctl` at it with [`DIFY_CONFIG_DIR`](/en/cli/reference/environment-variables). For a container, mount the directory at runtime instead of baking it into the image:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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](/en/cli/authenticate#sign-in-again), not retry. See [Handle Errors and Retries](/en/cli/integrate-agents/error-handling-and-retries-for-agents#branch-on-the-exit-code) for how to branch on it.

To revoke a session you suspect is compromised, run [`auth devices revoke`](/en/cli/reference/auth-and-contexts#revoke-sessions) from any signed-in machine.