Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.2501.ai/llms.txt

Use this file to discover all available pages before exploring further.

Import multiple hosts and their associated agents at once using CSV files. This is ideal for provisioning new infrastructure or migrating existing setups to 2501.

​
CSV Format

Your CSV file must include these columns in order: 
host_external_id,host_name,host_tags,host_private_ip,host_public_ip,host_target_type,agent_name,agent_configuration_name,agent_main_engine,agent_secondary_engine,agent_credential_1_name,agent_credential_1_source_type,agent_credential_1_role,agent_credential_1_value,agent_credential_2_name,agent_credential_2_source_type,agent_credential_2_role,agent_credential_2_value

​
Example CSV

host_external_id,host_name,host_tags,host_private_ip,host_public_ip,host_target_type,agent_name,agent_configuration_name,agent_main_engine,agent_secondary_engine,agent_credential_1_name,agent_credential_1_source_type,agent_credential_1_role,agent_credential_1_value,agent_credential_2_name,agent_credential_2_source_type,agent_credential_2_role,agent_credential_2_value
web-prod-001,Production Web Server,"web-01,app-server-01",10.0.1.10,203.0.113.45,ssh,WebApp Agent,SYSOPS,deepseek/deepseek-v3-together,qwen/qwen3-235b-openrouter,web-user,secret,remote_username,admin,web-pass,secret,remote_password,secretpass123
staging-001,Staging Server,staging-01,10.0.2.10,,ssh,Staging Agent,SYSOPS,qwen/qwen3-235b-openrouter,zai/glm-4-6-openrouter,staging-user,secret,remote_username,stagingadmin,staging-pass,secret,remote_password,stagingpass
win-app-001,Windows Server,win-app-01,10.0.3.10,203.0.113.47,winrm,Windows Agent,CLOUD_ARCHITECT_2,deepseek/deepseek-v3-together,qwen/qwen3-235b-openrouter,win-user,secret,remote_username,administrator,win-pass,secret,remote_password,winpass123
monitor-001,Monitoring Server,,10.0.5.10,203.0.113.48,ssh,,,,,,,,,,,,

​
Field Requirements

​
Host Fields (Required)

host_external_id — Unique identifier for the host within your organization. Used for idempotent imports (e.g., web-prod-001) host_name — Display name for the host (e.g., Production Web Server) host_target_type — Connection protocol: ssh or winrm

​
Host Fields (Optional)

host_tags — Comma-separated additional names used to identify the host (e.g., web-01,app-server-01) host_private_ip — Internal network IP address (e.g., 10.0.1.10) host_public_ip — External IP address (e.g., 203.0.113.45)

​
Agent Fields

Leave all agent and credential fields empty to create a host without an agent. agent_name — Display name for the agent (e.g., WebApp Agent) agent_configuration_name — Must match an existing Specialty key (not the display name). See Specialties for available keys. agent_main_engine — Primary LLM model (e.g., deepseek/deepseek-v3-together) agent_secondary_engine — Fallback LLM model (e.g., qwen/qwen3-235b-openrouter)

​
Credential Fields

When an agent is specified, all 8 credential fields are required (2 credentials per agent). agent_credential_X_name — Credential name. If a credential with this name already exists in the organization, it will be reused. agent_credential_X_source_type — Either secret (value stored directly) or vault_path (reference to external vault) agent_credential_X_role — One of:
  • remote_username — SSH/WinRM username
  • remote_password — SSH/WinRM password
  • remote_private_key — SSH private key
  • remote_public_key — SSH public key
agent_credential_X_value — The credential value:
  • For secret: the actual username, password, or key content
  • For vault_path: the path in your vault (e.g., secret/db/user)

​
Multiple Agents per Host

To assign multiple agents to one host, repeat the host row with the same host_external_id and host_name: 
host_external_id,host_name,host_tags,host_private_ip,host_public_ip,host_target_type,agent_name,agent_configuration_name,agent_main_engine,agent_secondary_engine,agent_credential_1_name,agent_credential_1_source_type,agent_credential_1_role,agent_credential_1_value,agent_credential_2_name,agent_credential_2_source_type,agent_credential_2_role,agent_credential_2_value
app-001,App Server,app-01,10.0.7.10,203.0.113.49,ssh,Application Agent,CLOUD_ARCHITECT_2,deepseek/deepseek-v3-together,qwen/qwen3-235b-openrouter,app-user,secret,remote_username,appuser,app-pass,secret,remote_password,apppass
app-001,App Server,app-01,10.0.7.10,203.0.113.49,ssh,Monitoring Agent,SYSOPS,zai/glm-4-6-openrouter,qwen/qwen3-235b-openrouter,mon-user,secret,remote_username,monuser,mon-pass,secret,remote_password,monpass
The host will be created once with two agents assigned.

​
Credential Reuse

Credentials are identified by name within the organization. If you import a CSV with a credential name that already exists:
  • The existing credential will be reused (no duplicate created)
  • The agent will be linked to the existing credential
This allows multiple agents to share the same credentials, and supports re-importing CSVs without creating duplicate credentials.

​
Importing via Command Center

  1. Go to Hosts
  2. Click Import Hosts
  3. Upload your CSV file
  4. Click Import
The system validates your CSV before import and reports any errors with line numbers.

​
Idempotent Imports

Each host_external_id can only be imported once per organization. Attempting to import a CSV containing an external_id that already exists will fail with an error listing the duplicates. This prevents accidental duplicate imports when re-running the same CSV.

​
Common Import Errors

Missing required columns — Ensure your CSV includes all 18 column headers in the exact order shown above. Empty host_external_id — Every row must have a non-empty host_external_id. Invalid host_target_type — Must be exactly ssh or winrm (lowercase). Configuration not found — The agent_configuration_name must match an existing Specialty’s key field, not its display name. Check Specialties for valid keys. Incomplete agent fields — If you specify agent_name, you must also provide agent_main_engine, agent_secondary_engine, and all 8 credential fields. Invalid credential source_type — Must be exactly secret or vault_path. Invalid credential role — Must be one of: remote_username, remote_password, remote_private_key, remote_public_key. host_name mismatch — If the same host_external_id appears multiple times, the host_name must match exactly across all rows. Duplicate external_id — A host with this host_external_id already exists in the organization.

​
Important Notes

  • Hosts are imported into the currently selected organization
  • All hosts and agents are created in a single transaction—if any validation fails, nothing is imported
  • Large imports (1000+ hosts) are supported efficiently
  • Agent workspace is automatically set based on target type: .2501/workspace for SSH, C:\ProgramData\2501\ for WinRM
  • Credentials with the same name are reused, not duplicated