> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Quickstart Guide

> Register, create a department, add a provider API key, create an Agent, and start from the command line

Get started with Alephant by registering your workspace, creating the agent identity and cost-control objects in the dashboard, then using the generated Virtual Key from your terminal or application.

## 1. Register for Alephant

Open the [Alephant dashboard](https://alephant.io/) and create an account or sign in to your workspace.

![Register for Alephant](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/c17ae247a2b52bc82225273c62bdab5ebb0b51e812f89303faa0f9bb06d78639/docs/assets/quickstart-register.png)

You can start on the Free plan without a credit card. After registration, continue to the workspace setup steps below.

## 2. Create a Department

In Enterprise workspaces, start by creating a department. Departments group members, agents, budgets, and usage attribution under one business unit.

![Create a new department](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/1b638edf1efa2f0d9a8c0fcdc0ad42b1a76660938e491f9de92c64e6ba82ddbe/docs/assets/quickstart-create-department.png)

Set a descriptive department name, monthly budget, and budget-exceeded behavior. This gives every Agent created under the department a clear cost center.

## 3. Add an API Key

Add your upstream provider key as a Master Key. Alephant stores the provider credential securely and uses it only when routing requests for your Agents.

![Add a provider API key](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/d7274e040843e1565dded7ed0be3428cabcf1eab6e71b0f17aa92927916cabcb/docs/assets/quickstart-add-api-key.png)

Choose your provider, continue to the key configuration step, then save the provider key. You can add keys for OpenAI, Anthropic, Gemini, OpenRouter, DeepSeek, AWS Bedrock, Azure OpenAI, or a custom OpenAI-compatible endpoint.

## 4. Create an Agent

Create an Agent for the application or workflow that will send AI traffic. The Agent generates a Virtual Key for client-side usage.

![Create an Agent](https://files.buildwithfern.com/alephantai.docs.buildwithfern.com/dfa3ad7405668dabe7ededb9b039c85aabce3f68f40f61b4b3ac64732663ab3c/docs/assets/quickstart-create-agent.png)

Bind the Agent to the department, choose the environment, set optional budget and rate-limit controls, then bind it to a Master Key. Copy the generated Virtual Key when the wizard completes.

## 5. Use the Virtual Key in Your App

After the Agent is created, use its Virtual Key directly in your application. The easiest path is to keep the OpenAI SDK, point it at Alephant, and send the Virtual Key in the `Authorization` header. Alephant then treats the call as agent traffic: it can route the model request, enforce policy, record cost, and attach the request to an Agent ID, Run ID, and session.

```typescript
import OpenAI from "openai";

const openai = new OpenAI({
  baseURL: "https://ai.alephant.io/v1",
  apiKey: process.env.ALEPHANT_VIRTUAL_KEY,
  defaultHeaders: {
    "Alephant-Agent-Id": "agt_support_bot_8f3a",
    "Alephant-Run-Id": "run_quickstart_001",
    "alephant-session-id": "session-1778033532814",
    "Alephant-Cache-Enabled": "true",
  },
});

const response = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Hello from Alephant" }],
});

console.log(response.choices[0]?.message?.content);
```

`Alephant-Agent-Id` identifies the Agent, `Alephant-Run-Id` identifies one task execution, and `alephant-session-id` groups related requests into one user or agent session. `Alephant-Cache-Enabled` enables cache behavior when supported by your workspace configuration.

## 6. Run Alephant MCP from the Command Line

Alephant MCP is distributed as `@alephantai/mcp`. Run it directly with the Agent's Virtual Key:

```bash
ALEPHANT_API_BASE_URL=https://alephant.io \
ALEPHANT_VIRTUAL_KEY=vk-... \
npx -y @alephantai/mcp
```

Run a one-shot audit to verify the connection:

```bash
ALEPHANT_API_BASE_URL=https://alephant.io \
ALEPHANT_VIRTUAL_KEY=vk-... \
npx --yes --package=@alephantai/mcp alephant-mcp --audit
```

In Virtual Key mode, the audit prints the key scope and billing-cycle usage summary.

## Next Steps

* [Configuration & Modes](/mcp-service/configuration-modes): choose Virtual Key mode or Manager mode.
* [Usage Guide](/mcp-service/usage-guide): ask Alephant MCP for spend, budget, model, and workspace insights.
* [Gateway Integration](/docs/overview/core-concepts/gateway-integration): send provider-compatible LLM traffic through Alephant.
* [Agent IDs And Run IDs](/docs/overview/core-concepts/agent-i-ds-and-run-i-ds): attach agent, run, session, request, and trace identifiers.