DocsICP FilingConsole
首页 AgentBay Developer Reference AgentBay CLI

AgentBay CLI

更新时间: 2026-05-15 14:54:33

AgentBay CLI is a command-line tool for managing AgentBay cloud development environments. Use it to automate image management and run batch operations in CI/CD pipelines.

Overview

Key features

  • Authentication management: Integrates with your Alibaba Cloud account using a secure OAuth-based sign-in mechanism.

  • Image management: Browse, create, activate, deactivate, and delete custom images, and view image status.

  • Image creation: Supports both cloud-based and local build modes.

  • Image activation: Activate custom image instances with custom resources, network configurations, and lifecycle management.

  • Image deactivation: Deactivate active image instances to release resources.

  • Template download: Download Dockerfile templates from the cloud.

  • API key management: Create API keys and set concurrency limits.

  • Skill management: Push local Skills to the cloud and view their details by ID.

  • Configuration management: Securely stores and automatically refreshes tokens.

  • Network management: List created network packages.

  • Image status: View the build and resource status of images.

Supported image types

Currently, the CLI tool supports creating and activating only CodeSpace custom images. The TYPE column in the image list output shows the underlying category, such as DockerBuilder or DedicatedDesktop, which is irrelevant to CLI operations.

Installation

Install with tap (recommended)

Quick install

# 1. Add the AgentBay Cloud Homebrew Tap
brew tap aliyun/agentbay

# 2. Install the agentbay command-line tool
brew install agentbay

# 3. Verify the installation
agentbay version

Usage

After installation, you can run these commands:

# Check the version information
agentbay version

# View help
agentbay --help

# Run an AgentBay command
agentbay [command] [options]

Update and uninstall

Upgrade to the latest version:

# Method 1: Upgrade only agentbay
brew upgrade agentbay

# Method 2: Try this if Method 1 fails
git -C $(brew --repository aliyun/agentbay) pull && brew upgrade agentbay

# Method 3: Try this if the first two methods fail
brew update
brew reinstall agentbay

Uninstall:

# Uninstall agentbay
brew uninstall agentbay

# Remove the Tap (optional)
brew untap aliyun/agentbay

Troubleshooting

1. Installation fails

# Update Homebrew
brew update

# Clean the cache
brew cleanup

# Reinstall
brew reinstall agentbay

2. Network issues

The formula uses a Chinese mirror source by default. If you still have issues:

# Set a Go proxy
export GOPROXY=https://goproxy.cn,direct
export GOSUMDB=sum.golang.google.cn

# Reinstall
brew reinstall agentbay

3. Permission issues

# Fix Homebrew permissions
sudo chown -R $(whoami) $(brew --prefix)/*

Manual installation

Download the latest version for your platform from GitHub Releases.

Quick start

Step 1: Log in

The CLI opens your browser for Alibaba Cloud authentication and returns to the terminal after you log in.

agentbay login

Step 2: View available images

# List only custom images (default)
agentbay image list

# Include system and custom images
agentbay image list --include-system

# Display only system images
agentbay image list --system-only

Step 3: Download a Dockerfile template

Download a Dockerfile template to the current directory. You must specify the source image ID. To list available system image IDs, run agentbay image list --system-only:

agentbay image init --sourceImageId code-space-debian-12

Step 4: Create a custom image

Cloud build

agentbay image create myapp --dockerfile Dockerfile --imageId code-space-debian-12

Local build

  1. Log in to Alibaba Cloud Container Registry (ACR) to get the registry path for pushing images:

    agentbay docker login

    Sample output:

    Credential expires at: 2026-05-11 12:28:55
Image registry path:   <your-registry-address>

WARNING! Your credentials are stored unencrypted in '/home/moushuai.ms/.docker/config.json'.
Configure a credential helper to remove this warning. See
https://docs.docker.com/go/credential-store/

Login Succeeded

Note: Credentials will expire after the time above. You can run 'agentbay docker login' again to refresh.
Note: When tagging images, use: <your-registry-address>:<your-tag>

  2. Build the Docker image locally:

    docker build -t <your-registry-address>:<your-tag> Dockerfile .

  3. Push the local Docker image to the ACR registry:

    docker push <your-registry-address>:<your-tag>

  4. Create an application image from the image in the registry:

    agentbay image create-from-template \
  --sourceImage /customer_cli/<your-account-id>:<your-tag> \
  --name myApp \
  --template code-space-debian-12

Step 5: Activate an image

Custom images must be activated before deployment. System images do not require activation.

agentbay image activate imgc-xxxxx...xxx

Step 6: Deactivate an image

Deactivate a custom image when it is no longer needed to release its allocated resources.

agentbay image deactivate imgc-xxxxx...xxx

Step 7: Create an API key

agentbay apikey create --name "my-api-key"

Step 8: Set session concurrency

agentbay apikey concurrency set --api-key-id ak-xxx --concurrency 10

Command reference

Global options

All commands support these global options:

  • --help, -h: Show help for the command.

  • --verbose, -v: Show verbose debug output.

  • --version: Show the CLI version.

Command structure

agentbay [global options] <command> [command options] [arguments]

Command index

AgentBay CLI commands grouped by function:

Command

Description

login / logout

Session management: Log in and out.

version

Show the CLI version.

image

Image management: List, create, activate, deactivate, and delete images.

network

Network package management: List network packages.

apikey

API key management: Create API keys and set concurrency limits.

skills

Skill management: Push skills to the cloud and view details.

Image management

Image activation and deactivation

  • Custom images: Must be activated before deployment.

  • System images: Always available and do not require activation.

  • Deactivating an image: Deactivate a custom image when it is no longer needed to free its compute resources.

Image list

Lists the available AgentBay images.

Syntax

agentbay image list [options]

Options

  • --os-type, -o <type>: Filters by operating system type (Linux, Android, or Windows).

  • --include-system: Displays both custom images and system images.

  • --system-only: Displays only system images.

  • --page, -p <number>: The page number (default: 1).

  • --size, -s <number>: The number of items to display per page (default: 10).

Examples

# List custom images
agentbay image list

# List Linux images
agentbay image list --os-type Linux

# List all images (custom + system)
agentbay image list --include-system

# List only system images
agentbay image list --system-only

# Query with pagination
agentbay image list --page 2 --size 5

Output description

The output includes these columns:

  • Image ID: The unique identifier for the image.

  • Image name: The name of the image.

  • Type: The image type (DockerBuilder or DedicatedDesktop).

  • Status: The status of the image.

  • OS: The operating system type and version.

  • Use case: The use case for the image.

Status description

  • Creating: The image is being built.

  • Available: The image build is complete and ready for activation.

  • Activated: The image is activated and running.

  • Create Failed: The image build failed.

Important

The image list command shows only an image's build status (such as Creating, Available, or Create Failed), not its resource status. The resource status is shown in the output of the image activate and image deactivate commands.

Note

  • System images are always available and do not require activation.

  • You must activate custom images before use.

  • By default, the command lists only custom images.

  • The image list is grouped by custom images and system images.

Image init

Downloads a Dockerfile template to the current directory for a specified base image.

Syntax

agentbay image init --sourceImageId <image-id>

Example

# Download a Dockerfile template
agentbay image init --sourceImageId code-space-debian-12

Example output

[INIT] Downloading Dockerfile template...
Requesting Dockerfile template... Done.
Downloading Dockerfile from OSS... Done.
Writing Dockerfile to /path/to/current/directory/Dockerfile...
[WARN] Dockerfile already exists at /path/to/current/directory/Dockerfile
[INFO] The existing file will be overwritten.
 Done.
[SUCCESS] Dockerfile template downloaded successfully!
[INFO] Dockerfile saved to: /path/to/current/directory/Dockerfile
[IMPORTANT] The first 5 line(s) of the Dockerfile are system-defined and cannot be modified.
[IMPORTANT] Please only modify content after line 5.
Note

  • If a Dockerfile already exists in the current directory, the command overwrites the existing file and displays a warning before doing so.

  • This step is optional. You can also create a Dockerfile manually or use an existing one.

  • IMPORTANT: The first N lines of the downloaded template are system-defined and must not be modified; N is specified in the command's output. Modifying these lines may cause the image build to fail. You can only add content after line N.

Image create

Creates a new AgentBay image from a Dockerfile.

Syntax

agentbay image create <image-name> --dockerfile <path> --imageId <base-image-id>

Arguments

  • <image-name>: The name for the custom image (required).

Options

  • --dockerfile, -f <path>: The path to the Dockerfile (required).

  • --imageId, -i <id>: The ID of the base image (required).

Examples

# Use full option names
agentbay image create my-app --dockerfile ./Dockerfile --imageId code-space-debian-12

# Use short option names
agentbay image create my-app -f ./Dockerfile -i code-space-debian-12

# Use verbose output mode
agentbay image create my-app -f ./Dockerfile -i code-space-debian-12 -v

Example output

[BUILD] Creating image 'my-app'...
[STEP 1/4] Getting upload credentials... Done.
[STEP 2/4] Uploading Dockerfile... Done.
[STEP 3/4] Uploading ADD/COPY files (N files)... Done.
[STEP 4/4] Creating Docker image task... Done.
[STEP 5/5] Building image (Task ID: task-xxxxx)...
[STATUS] Build status: RUNNING
[SUCCESS] Image created successfully!
[RESULT] Image ID: imgc-xxxxx...xxx

Build process

  1. Gets upload credentials.

  2. Uploads the Dockerfile to object storage.

  3. Uploads files referenced by ADD/COPY instructions, if present in the Dockerfile.

  4. Creates a Docker image build task.

  5. Starts the image build.

ADD/COPY file uploads

When creating an image, the CLI parses the COPY and ADD instructions in the Dockerfile and uploads the referenced local files. Paths are relative to the directory containing the Dockerfile. Supports single files, multiple files, subdirectories, and wildcards (such as *.py). Absolute paths, path traversal (such as ../), and URL sources for the ADD instruction are not supported. All files referenced by COPY or ADD must exist in the Dockerfile directory or its subdirectories.

Note

  • The build time depends on the image size and complexity.

  • Use the -v option to view detailed build logs.

  • You can check the build status by running image list during the process.

  • The base image ID must be a valid system image ID. To view available system images, run image list --system-only.

Image activate

Activates a custom image to make it available for deployment.

Syntax

agentbay image activate <image-id> [options]

Arguments

  • <image-id>: The ID of the image to activate (required).

Options

  • --cpu, -c <cores>: The number of CPU cores (2, 4, 8, or 16).

  • --memory, -m <GB>: The amount of memory in GB (4, 8, 16, or 32).

  • --network-type: Specifies the network type. Use ADVANCED for the advanced network or DEFAULT for the basic network. Defaults to the basic network if unspecified.

  • --session-bandwidth: Sets the maximum public bandwidth per session, in Mbps. The value must be between 2 and 200. This option applies only to the advanced network. If unspecified, bandwidth is unlimited.

  • --dns-address: The IP address of a DNS server. This option is available only for the advanced network and is optional. You can specify this option multiple times to configure multiple DNS servers.

  • --lifecycle-mode: Sets the release mode for the sandbox lifecycle. In auto mode, compute resources are released automatically based on lifecycle policies. In manual mode, you must deactivate the image to release resources.

  • --lifecycle-max-runtime: The maximum runtime in minutes. Requires --lifecycle-mode to be set to auto.

  • --lifecycle-hibernate: The maximum hibernation duration in hours. Requires --lifecycle-mode to be set to auto.

  • --lifecycle-idle-timeout: The maximum idle duration in minutes. Requires --lifecycle-mode to be set to auto.

Supported resource configurations

  • 2c4g: 2 CPU cores, 4 GB memory (default configuration if not specified).

  • 4c8g: 4 CPU cores, 8 GB memory.

  • 8c16g: 8 CPU cores, 16 GB memory.

  • 16c32g: 16 CPU cores, 32 GB memory.

Important

Activating an image allocates compute resources and incurs charges. To avoid unnecessary costs, deactivate images promptly when they are no longer needed.

Examples

# Activate with the default resource configuration (2c4g)
agentbay image activate imgc-xxxxx...xxx

# Activate with a 2c4g configuration
agentbay image activate imgc-xxxxx...xxx --cpu 2 --memory 4

# Activate with a 4c8g configuration
agentbay image activate imgc-xxxxx...xxx --cpu 4 --memory 8

# Activate with an 8c16g configuration
agentbay image activate imgc-xxxxx...xxx --cpu 8 --memory 16

# Activate with a 16c32g configuration
agentbay image activate imgc-xxxxx...xxx --cpu 16 --memory 32

# Use verbose output
agentbay image activate imgc-xxxxx...xxx --cpu 4 --memory 8 -v

# Advanced network - minimal form
agentbay image activate imgc-xxxx --network-type ADVANCED

# Advanced network - with bandwidth configuration
agentbay image activate imgc-xxxx --network-type ADVANCED --session-bandwidth 10

# Advanced network - with DNS configuration
agentbay image activate imgc-xxxx \
  --network-type ADVANCED \
  --dns-address 8.8.8.8 \
  --dns-address 8.8.4.4

# Advanced network - full configuration
agentbay image activate imgc-xxxx \
  --cpu 8 \
  --memory 16 \
  --network-type ADVANCED \
  --session-bandwidth 10 \
  --dns-address 8.8.8.8 \
  --dns-address 114.114.114.114

# Sandbox lifecycle - manual release
agentbay image activate imgc-xxxx --lifecycle-mode manual

# Sandbox lifecycle - automatic release with max runtime
agentbay image activate imgc-xxx --lifecycle-mode auto --lifecycle-max-runtime 30

# Sandbox lifecycle - full configuration
agentbay image activate imgc-xxxx \
  --lifecycle-mode auto \
  --lifecycle-max-runtime 50 \
  --lifecycle-hibernate 40 \
  --lifecycle-idle-timeout 30

Example output

[ACTIVATE] Activating image...
Checking current image status... Done.
Creating resource group... Done.
Waiting for activation to complete...
  Status: Activating (elapsed: 5s, attempt: 2/60)
  Status: Activating (elapsed: 13s, attempt: 3/60)
[SUCCESS] Image activated successfully!

Usage notes

  • Only custom images can be activated.

  • System images are always available and do not require activation.

  • The --cpu and --memory options must be specified together and must match a supported configuration.

  • If you omit the CPU and memory options, the default configuration (2c4g) is used.

  • The activation process typically takes 1 to 2 minutes.

  • If the image is already activated, the command reports that no action is needed.

  • During activation, the command polls the image status. The polling interval increases over time. The command makes up to 60 attempts with a total timeout of 30 minutes.

Image deactivate

Deactivates an active custom image and releases its associated resources.

Syntax

agentbay image deactivate <image-id>

Arguments

  • <image-id>: The ID of the image to deactivate (required).

Examples

# Deactivate an image
agentbay image deactivate imgc-xxxxx...xxx

# Use verbose output
agentbay image deactivate imgc-xxxxx...xxx -v

Example output

[DEACTIVATE] Deactivating image...
Deleting resource group... Done.
Waiting for deactivation to complete...
  Status: Deactivating (elapsed: 5s, attempt: 2/40)
[SUCCESS] Image deactivated successfully!

Usage notes

  • Deactivation typically takes 1 to 2 minutes. The command polls the image status up to 40 times, with a total timeout of about 20 minutes.

  • After deactivation is complete, you can run agentbay image list to confirm that the resources have been released.

  • Deactivating an image releases the associated compute resources and stops billing.

Image delete

Permanently deletes a custom image. This action is irreversible.

Prerequisites

Deactivate the image to release its compute resources before deleting it. Run agentbay image deactivate <image-id>.

Syntax

agentbay image delete <image-id>

Arguments

  • <image-id>: The ID of the image to delete (required).

Examples

# 1. First, deactivate the image (prerequisite)
agentbay image deactivate imgc-xxxxxxxxxxxxxx

# 2. Delete interactively (prompts for y/N confirmation)
agentbay image delete imgc-xxxxxxxxxxxxxx

# 3. Skip confirmation in a script or CI environment
agentbay image delete imgc-xxxxxxxxxxxxxx --yes

# 4. Verify the deletion (the image no longer appears in the list)
agentbay image list

Example output

[DELETE] Deleting image 'imgc-0ab5ta4nzbwu9bvaa'...
Checking current image status... Done.
[INFO] GetMcpImageInfo Request ID: 3DFFDC7F-9EC2-10BA-878B-EE1E54D00245
[INFO] Image Type: User
[INFO] Current Status: Available (Deactivated)
Are you sure you want to permanently delete image 'imgc-0ab5ta4nzbwu9bvaa'? This action is irreversible. [y/N]: y
Deleting image... Done.
[INFO] DeleteMcpImage Request ID: 2EB74FE6-5757-167F-B71E-0C474ED0419B
[SUCCESS] Image 'imgc-0ab5ta4nzbwu9bvaa' has been permanently deleted.
Warning

Deleting an image is permanent and irreversible. Before deleting, run agentbay image deactivate <image-id> to deactivate it and confirm that all related resources are released.

Image status

Displays the detailed build and resource status of a specific image.

Syntax

agentbay image status <image-id>

Arguments

  • <image-id>: The ID of the image whose status you want to view (required).

Example

agentbay image status imgc-xxxxx...xxx

Status description

Image status is divided into two categories: build status and resource status.

Category

Value

Description

Build status

IMAGE_CREATING

The image is being built.

Build status

IMAGE_CREATE_FAILED

Image creation failed.

Build status

IMAGE_AVAILABLE

The image is available and can be activated.

Resource status

RESOURCE_DEPLOYING

Compute resources are being deployed.

Resource status

RESOURCE_PUBLISHED

Compute resources are deployed and ready for use.

Resource status

RESOURCE_DELETING

Compute resources are being released.

Resource status

RESOURCE_FAILED

Compute resource deployment failed.

Resource status

RESOURCE_CEASED

Compute resources are stopped.

Network package management

View your assigned network packages, including their associated office sites and elastic IP addresses. Currently, only the list operation is supported.

network package list — List network packages

Syntax

agentbay network package list [options]

Options

  • --biz-region-id <region-id>: The region ID (default: cn-hangzhou).

Examples

# List network packages in the default China (Hangzhou) region
agentbay network package list

# Query network packages in another region
agentbay network package list --biz-region-id cn-shanghai

Output

The output includes these columns:

  • Network package ID: The unique identifier of the network package.

  • Office site ID: The ID of the associated office site.

  • EIP addresses: The bound elastic IP addresses (EIPs).

Usage notes

Note

  • By default, the command queries the cn-hangzhou region. Use the --biz-region-id option to specify a different region.

  • If no network packages exist in the specified region, the CLI prints "No network packages found".

  • Use the -v option to view debug information, such as the request ID.

API key management

These commands require authentication. Run agentbay login first.

apikey create

Syntax

agentbay apikey create --name <name>

Options

  • --name <name>: The name of the API key (required).

Example

agentbay apikey create --name "my-api-key"

Example output

API Key created successfully.
  ID:      ak-xxxxxxxxxxxx
  Name:    my-api-key
  Created: 2025-01-15 10:30:00

Verification

After creation, run agentbay apikey list to view your API keys.

apikey concurrency set

Syntax

agentbay apikey concurrency set --api-key-id <api-key-id> --concurrency <number>

Options

  • --api-key-id <api-key-id>: The API key ID (required).

  • --concurrency <number>: The concurrency limit, which must be 1 or greater (required).

Example

agentbay apikey concurrency set --api-key-id ak-xxxxx --concurrency 5

Verification

View the API key details to verify the new concurrency limit.

Skill management

Skill commands require authentication. Run agentbay login first. Use these commands to upload local skills to the cloud and manage them.

skills — Skill command group

Syntax

agentbay skills <subcommand> [parameters] [options]

Subcommands

  • push: Pushes a local skill (a directory or a .zip file) to the cloud.

  • show: Displays details for a specified skill.

Global options (shared with subcommands)

  • --verbose, -v: Enables verbose output, displaying debugging information such as the upload URL, upload size, and RequestId.

  • --help: Displays help information.

skills push — Push a skill

Pushes a local skill to the cloud. The CLI gets an upload credential, uploads the zip file, and creates the skill. Provide either the skill's root directory (containing a SKILL.md file) or a pre-packaged .zip file.

Syntax

agentbay skills push <skill-dir>|<skill.zip>

Parameters

  • <skill-dir>: The path to the skill's root directory. The directory must contain a SKILL.md file. The CLI validates the required metadata, then packages the directory into a zip file for upload.

  • <skill.zip>: The path to a zip file. The file is uploaded as is.

SKILL.md requirements (directory mode)

  • Must include a name: line specifying the skill name (required). For example: name: my-skill.

  • You can also include a description: line to provide the skill's description.

  • YAML-style front matter is recommended:

---
name: my-skill
description: Optional description
---

# Skill content

Uploaded file naming

  • Directory mode: The zip filename is formed by appending .zip to the directory's base name. For example, for the directory ./pdf, the uploaded filename is pdf.zip. If the base name is empty or ., skill.zip is used.

  • Zip mode: The name of the provided zip file is used as is.

Execution flow

  1. [STEP 1/3] Get an upload credential, such as a presigned URL.

  2. [STEP 2/3] Upload the file: Directories are zipped before uploading; zip files are uploaded directly.

  3. [STEP 3/3] Call the Create Skill API. On success, the command prints the resulting skill ID.

Examples

# Push from a directory containing SKILL.md
agentbay skills push ./my-skill

# Push a pre-packaged zip file
agentbay skills push ./my-skill.zip

# Use verbose output
agentbay skills push ./my-skill -v

Example output

[STEP 1/3] Getting upload credential...
[STEP 2/3] Packing and uploading skill...
[STEP 3/3] Creating skill...

[SUCCESS] Skill created successfully!
[RESULT] Skill ID: <skill-id>
Note

  • The path must point to an existing directory or a file with a .zip extension.

  • In directory mode, the command fails if the SKILL.md file is missing or lacks the name: line. The error message includes instructions to fix the issue.

  • Zip file entries are compressed using the DEFLATE algorithm.

skills show — Show skill details

Displays the details of a specified skill.

Syntax

agentbay skills show <skill-id>

Parameters

  • <skill-id>: The unique identifier for the skill. This is the ID returned in the [RESULT] output from a successful skills push command.

Output

  • Skill ID: The skill's unique identifier.

  • Name, description: The name and description of the skill. Long descriptions wrap and indent automatically for readability.

Examples

# Show Skill details
agentbay skills show <skill-id>

# Show verbose output
agentbay skills show <skill-id> -v

Authentication management

login

Syntax

agentbay login

Login process

  1. Starts a local callback server.

  2. Opens a browser for Alibaba Cloud authentication.

  3. Receives an authorization code and exchanges it for an access token.

  4. Saves the authentication tokens to a local configuration file.

Example output

Starting AgentBay authentication...
Starting local callback server on port 3001...
Opening browser for authentication...
Browser opened successfully!
Waiting for callback on http://localhost:3001/callback...
Authentication successful!
Received authorization code: xxxxx...
Exchanging authorization code for access token...
Saving authentication tokens...
Authentication tokens saved successfully!
You are now logged in to AgentBay!
Note

  • If you are already logged in and the token has not expired, the command notifies you that you are already logged in.

  • If the browser fails to open automatically, the command prints the authentication URL. You can copy this URL into your browser to proceed.

  • The authentication timeout is 5 minutes.

  • Tokens refresh automatically, so you do not need to log in frequently.

Troubleshooting

If port 3001 is in use, check what's using it:

  • macOS/Linux: lsof -i :3001

  • Windows: netstat -ano | findstr :3001

logout

Syntax

agentbay logout

Logout process

  1. Attempts to revoke the server-side refresh token.

  2. Clears the authentication tokens from the local configuration file.

Example output

Logging out from AgentBay...
Revoking server tokens...
Refresh token revoked successfully
Clearing local authentication data...
Successfully logged out from AgentBay
Note

  • Local data is cleared even if the server-side revocation fails.

  • Access tokens are short-lived and expire automatically.

  • Revoking a refresh token also invalidates the associated access tokens.

version

Syntax

agentbay version

Example output

AgentBay CLI version 1.0.0
Git commit: abc1234
Build date: 2025-01-15
Environment: production
Endpoint: xiaoying-share.cn-shanghai.aliyuncs.com

Output fields

  • Version: The CLI's version number.

  • Git commit: The Git commit hash at build time.

  • Build date: The date when the CLI was built.

  • Environment: The current environment (production or prerelease).

  • Endpoint: The current API endpoint.

Configuration

Configuration file structure

The JSON configuration file contains:

  • Access token

  • Refresh token

  • ID token

  • Token type

  • Expiration time

Token management

The CLI manages tokens automatically:

  • Auto-refresh: Uses a refresh token to get a new access token before the current one expires.

  • Secure storage: Stores tokens in the user's configuration directory, accessible only to the current user.

  • Token validation: Checks token validity before each API call.

Environment variables

You can also configure the CLI with environment variables:

  • AGENTBAY_ENV: The runtime environment. Valid values: prod (production environment), pre (prerelease environment), and international (international site).

  • AGENTBAY_CLI_ENDPOINT: An optional variable to override the default API endpoint.

FAQ

Authentication

Q: What should I do if I get a "port already in use" error when logging in?

A: This error means another program is using port 3001. To resolve this:

  1. Close the program that is using the port.

  2. Use lsof -i :3001 (macOS/Linux) or netstat -ano | findstr :3001 (Windows) to find the process.

  3. Terminate the process and try again.

Q: What if the browser does not open automatically for authentication?

A: The CLI displays the authentication URL. Copy and paste it into your browser to complete authentication.

Q: What happens if the login process times out?

A: Authentication times out after 5 minutes. If it expires, run agentbay login again.

Q: How can I check my current login status?

A: Run any command that requires authentication, such as agentbay image list. If you are not logged in or your session has expired, the CLI prompts you to log in.

Images

Q: How do I view available base images?

A: Use agentbay image list --system-only to view all system images that you can use as base images.

Q: What should I do if my image build fails?

A: Check these:

  1. Verify that the Dockerfile syntax is correct.

  2. Ensure that the provided base image ID is valid.

  3. Confirm that you have not modified the system-defined header lines at the top of the Dockerfile.

  4. Use the -v option to view detailed error logs.

  5. Download a template by running agentbay image init -i <system-image-id>. You can find system image IDs by running agentbay image list --system-only.

Q: Which parts of the Dockerfile cannot be modified?

A: In a Dockerfile template downloaded with agentbay image init, the first N lines are system-defined and cannot be modified. After the command succeeds, the output specifies N:

[IMPORTANT] The first 5 line(s) of the Dockerfile are system-defined and cannot be modified.
[IMPORTANT] Please only modify content after line 5.

Only modify content after line N. Modifying these initial N lines can cause the image build to fail.

Q: How do I check the image build status?

A: Run agentbay image list to check the build status. To view the full image and resource status, use agentbay image status <image-id>.

Q: How long does it take to activate an image?

A: Activation typically takes 1 to 2 minutes. The CLI displays progress updates.

Q: Can I activate multiple images at the same time?

A: Yes. Each image is managed independently, so you can activate multiple images concurrently without conflicts.

Q: Is data lost when an image is deactivated?

A: No. Deactivating an image releases its associated compute resources, but the image itself is not deleted and can be reactivated.

Command usage

Q: How can I get help for a command?

A: Use the --help or -h option with any command or subcommand to see its options and usage:

agentbay --help
agentbay image --help
agentbay image create --help

Q: How do I enable verbose logs?

A: Use the -v or --verbose option with a subcommand for more detailed output:

agentbay -v image create my-app -f ./Dockerfile -i code-space-debian-12

Q: Where is the configuration file located?

A:

  • macOS/Linux: ~/.config/agentbay/config.json

  • Windows: %APPDATA%\agentbay\config.json

Q: How can I reset my configuration?

A: Delete the configuration file and then log in again:

# macOS/Linux
rm ~/.config/agentbay/config.json

# Windows
del %APPDATA%\agentbay\config.json

Error handling

Q: What should I do if I encounter a "Request ID" error?

A: If an error message includes a Request ID, save this ID and provide it when you contact technical support.

Q: What should I do if I have network connectivity issues?

A: Check these:

  1. Check that your internet connection is working.

  2. Check that your firewall is not blocking the connection.

  3. Check that you can reach the AgentBay service endpoint.

Switch environments

Overview

AgentBay CLI lets you switch between production and prerelease environments. This feature is mainly for internal development and testing.

Environments

  • Production environment (production): The default environment for official use.

  • Prerelease environment (prerelease): For testing and verification.

  • International site environment (international): Lets you access international site services.

Switching methods

Temporary switch

AGENTBAY_ENV=prerelease agentbay login

Session-level switch

# macOS/Linux
export AGENTBAY_ENV=prerelease
agentbay login
agentbay image list

# Windows (PowerShell)
$env:AGENTBAY_ENV="prerelease"
agentbay login
agentbay image list

Permanent switch

# macOS/Linux - Add to ~/.zshrc or ~/.bashrc
echo 'export AGENTBAY_ENV=prerelease' >> ~/.zshrc
source ~/.zshrc

# Windows - Add to your system environment variables

Switch back to production

# Unset the environment variable
unset AGENTBAY_ENV

# Or explicitly set it to the production environment
export AGENTBAY_ENV=production

Verify the current environment

Run agentbay version to check the current environment:

agentbay version

The Environment field in the output shows the current environment.

Use the international site

To use the international site for overseas regions, set the environment to international.

Environment variables

  • AGENTBAY_ENV=international: Uses the international site.

  • Optional override: AGENTBAY_CLI_ENDPOINT.

Example (for the current session)

# macOS/Linux
export AGENTBAY_ENV=international
agentbay login
agentbay image list

# Windows (PowerShell)
$env:AGENTBAY_ENV="international"
agentbay login
agentbay image list

After setting the variable, run agentbay version to confirm the current environment and endpoint.

Supported environment values

  • Production environment: production, prod, or unset (default).

  • Prerelease environment: prerelease, pre, or staging.

  • International site: international.

Notes

Note

  • Each environment uses a separate authentication token. You must log in to each one individually.

  • Images and resources are not shared between environments.

  • You must log in again after switching environments.

  • This feature is mainly for internal testing. Most users should use the default production environment.

Technical support

If you encounter an issue, provide:

  1. CLI version (agentbay version).

  2. Error message, including the Request ID.

  3. Steps to reproduce the issue.

  4. System information (operating system and version).

Appendix

Resource configuration reference

The image activate command lets you customize resource configurations with the --cpu and --memory parameters. Both parameters accept integer values.

Supported vCPU and memory combinations:

vCPU

Memory (GB)

Parameter

2

4

2c4g (default)

4

8

4c8g

8

16

8c16g

16

32

16c32g

上一篇: Code Space 下一篇: Client-Side Integration