OverviewGetting Started

Quickstart Guide

View as Markdown

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 and create an account or sign in to your workspace.

Register for Alephant

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

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

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

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.

1import OpenAI from "openai";
2
3const openai = new OpenAI({
4  baseURL: "https://ai.alephant.io/v1",
5  apiKey: process.env.ALEPHANT_VIRTUAL_KEY,
6  defaultHeaders: {
7    "Alephant-Agent-Id": "agt_support_bot_8f3a",
8    "Alephant-Run-Id": "run_quickstart_001",
9    "alephant-session-id": "session-1778033532814",
10    "Alephant-Cache-Enabled": "true",
11  },
12});
13
14const response = await openai.chat.completions.create({
15  model: "gpt-4o-mini",
16  messages: [{ role: "user", content: "Hello from Alephant" }],
17});
18
19console.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:

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

Run a one-shot audit to verify the connection:

$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