> ## 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 Hosts via CSV

> Bulk import hosts and agents using CSV files

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:

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

```csv theme={null}
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`)

<Note>
  Despite its name, the `host_tags` column populates a host's **Additional Names** (free-form aliases), not the structured OS, Shell, Type, and Technologies tags. Those tags are a closed vocabulary that you assign in Command Center on each host's detail page after import. See [Hosts: Host Tags](/0.7/core-concepts/hosts#host-tags).
</Note>

**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](/0.7/configure/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`:

```csv theme={null}
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 Hosts** to submit

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
* The entire CSV is validated before any data is written, so if any row fails validation, nothing is imported
* Large imports (1000+ hosts) are supported efficiently
* Credentials with the same name are reused, not duplicated