Quickstart - - Alibaba Cloud Documentation Center

Get your first Qoder Cloud Agent running in 5 steps: get a token, select an environment, create an agent, create a session, and send and receive messages. All you need is curl—no SDK installation is required.

Prerequisites

A Qoder account
A terminal environment (macOS, Linux, or WSL)
curl and jq (optional, for formatting JSON output)

For Windows users: The commands in this document use bash syntax. We recommend using Git Bash (included with Git for Windows) or WSL (install with wsl --install). If you use PowerShell, you must adapt the commands: set an environment variable with $env:QODER_PAT="your-token", use curl.exe to bypass PowerShell's curl alias, and install jq separately (e.g., winget install jqlang.jq).

Step 1: Get a PAT

Sign in to the Qoder Console.
Navigate to Settings > Personal Access Tokens.
Click **Create Token**, then set a name and expiration.
Copy the token and set it as an environment variable:

export QODER_PAT="your-token-here"

Your token is shown only once upon creation. Save it to a safe place immediately. For convenience, add the export command to your shell's startup file, such as ~/.bashrc or ~/.zshrc.

Step 2: Select an environment

List your available environments to get an environment ID:

curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" | jq .

If the response returns "data": [] (an empty array), your account has no environments yet. Create one as follows:

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{"name": "default", "config": {"type": "cloud", "networking": {"type": "unrestricted"}}}' | jq .

Step 3: Create an agent

Define a general-purpose agent with shell tools:

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-agent",
    "model": "ultimate",
    "instructions": "You are a helpful coding assistant.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }' | jq .

Note the id field in the response (e.g., agent_019e...). You will need it to create a session in the next step.

Step 4: Create a session

Creating a session requires two parameters: agent (the agent ID or object) and environment_id (the environment ID).

Bind the agent to an environment to create a running instance:

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_YOUR_AGENT_ID",
    "environment_id": "env_YOUR_ENV_ID"
  }' | jq .

After creation, the session enters an idle state. The agent begins executing only after you send it a message in the next step.

Step 5: Send a message and receive events

Send a user message to the session, then receive the agent's responses in real-time from an SSE stream:

# Send a message
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "user.message",
    "content": [{"type": "text", "text": "Write a Python function that calculates fibonacci numbers"}]
  }'

# Receive the SSE event stream
curl -sN "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_YOUR_SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"

The API sends a heartbeat event approximately every 15 seconds to keep the connection alive. The content field of an agent.message event uses an array format: [{"type":"text","text":"..."}].

FAQ

Q: What should I do if I get a 401 Unauthorized error?

A: Check that the $QODER_PAT environment variable is set correctly and your token has not expired. If needed, create a new token and update the environment variable.

Q: Why do I get a 400 Bad Request error when creating an agent?

A: Check that the request body is valid JSON. Ensure the model field is a valid value (e.g., "ultimate") and that the tools field is an array.

Q: Why is my session stuck in an idle state and not receiving events?

A: A session is idle by default after creation. You must send a user.message event to trigger the agent. Ensure you have performed Step 5 correctly.

Q: What should I do if the SSE stream connection is interrupted?

A: We recommend saving the id of the last event received before the disconnection (e.g., evt_...). When reconnecting, include the ?after_id=<last_event_id> query parameter. The server will then resume sending events from where you left off.

Q: Why does GET /environments return an empty array?

A: New accounts may not have a pre-configured environment. Create one as described in Step 2.