Quickstart

3 min read Updated 2026-10-16 View as Markdown Report a problem

This guide takes you from nothing to a working request through the hosted service. On a self-hosted installation the steps are the same; replace https://acog.tessarac.com with your installation’s address.

You need an account with at least one AI provider (for example an Anthropic API key, or a Google Cloud project with Vertex AI enabled).

Go to acog.tessarac.com and choose Sign in or create your account. The first time you sign in you are asked to name your organization. You become its admin.

Everything in ACOG belongs to an organization: provider connections, keys, usage, savings and invoices. Nothing is shared between organizations.

2. Connect a provider

Open Admin → Providers and choose Connect provider.
Pick the platform (Direct, Bedrock, Vertex, Azure or Custom) and the model family.
Enter the credentials. For Google Vertex AI and Anthropic you can choose Keyless (workload identity) instead of storing a key; see Keyless connections.
Review the models ACOG found in your account and choose a default model.

ACOG checks the credentials when you save. The secret is encrypted and is never shown again. The provider pages explain each platform’s fields: Anthropic, OpenAI, Google Vertex AI, AWS Bedrock, Azure OpenAI and custom endpoints.

3. Switch on savings

A new hosted organization starts in pass-through mode: requests work, but they are forwarded unchanged at full price and nothing is saved. To switch the savings on, add a payment method under Admin → Billing. You are billed only a share of what ACOG measurably saves, monthly. See Billing.

You can do the rest of this guide first and add the payment method later.

4. Create a gateway key

Open Developer and create a key. Give it a name that says where it will be used, for example laptop or billing-service.
Copy the key. It starts with acog_ and is shown only once: ACOG stores only a hash of it.
Store it as an environment variable:

export ACOG_API_KEY="acog_..."

A key you create for yourself carries your permissions and your usage is attributed to you. Admins can also create service keys for applications. See API keys.

5. Check the key

This call reaches no provider and costs nothing. It lists the models your key can use:

curl -s https://gateway.acog.tessarac.com/v1/models \
  -H "Authorization: Bearer $ACOG_API_KEY"

Status	Meaning
`200`	The key works. The list is what it can route to; an empty list means no provider is connected yet.
`401`	The key was not read: it is missing, revoked, or in a header ACOG does not read.
`403`	The key is valid but lacks the gateway access permission (`proxy`).
`503`	ACOG could not reach its key store. This is not your key; retry.

6. Send a request

Use any model you declared on a connection. ACOG speaks both the OpenAI and the Anthropic API, and translates between them, so either SDK can reach any of your models.

curl (OpenAI-compatible)

curl -s https://gateway.acog.tessarac.com/v1/chat/completions \
  -H "Authorization: Bearer $ACOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "Hello"}]}'

Python, OpenAI SDK

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.acog.tessarac.com/v1",
    api_key=os.environ["ACOG_API_KEY"],
)

completion = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Hello"}],
)
print(completion.choices[0].message.content)

Python, Anthropic SDK

import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://gateway.acog.tessarac.com",
    # Pass the gateway key as auth_token (sent as Authorization: Bearer), not api_key.
    auth_token=os.environ["ACOG_API_KEY"],
)

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=256,
    messages=[{"role": "user", "content": "Hello"}],
)
print(message.content[0].text)

Node.js, OpenAI SDK

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.acog.tessarac.com/v1",
  apiKey: process.env.ACOG_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "gpt-4.1-mini",
  messages: [{ role: "user", content: "Hello" }],
});
console.log(completion.choices[0].message.content);

The two base URLs differ only because of the path each SDK appends: the OpenAI SDK expects /v1 in the base URL and the Anthropic SDK adds its own. See Base URLs and authentication.

To let ACOG pick the model, send "model": "auto". See Auto mode.

7. See the result

Open Overview in the console. Within a few seconds the request appears with its cost and what it would have cost sent directly. Reports → Recent requests shows each request’s model, tokens, cost and saving.

Next steps

Point your coding assistant at ACOG: Use ACOG with coding tools.
Set spending limits: Budgets.
Invite your team: Users and invitations.

1. Sign in and create your organization