FAQ
Short answers to the questions people actually ask in their first week on the Crusoe Agent Platform. Each one links to the page that explains it properly.
Getting started
How do I get an account?
Someone has to give you one. There is no self-service sign-up page. An administrator either creates your account (and hands you a one-time temporary password you must change at first sign-in) or sends you an invitation link to a project, which lets you choose your own password when you accept. Either way, sign in at https://console.codyhill.dev. See create an account.
Do I need to know Kubernetes? Do I need a cluster?
No to both. You give the platform a folder of code or a container image, and it gives you back a URL. The platform runs the containers, the scaling, the networking, and the certificates. You never write a Kubernetes manifest.
What do I need installed?
Nothing, if you use the web console — the console can write, upload, deploy, and chat with an agent entirely in the browser. For scripting and for anything larger than 32 MiB, install the platformctl command-line tool. See install the CLI.
Is there a public API URL I can point my scripts at?
Not in the alpha, and we would rather say so than pretend otherwise. The web console is the public front door. Automation reaches the API either through an endpoint your administrator gives you (set it as CAI_API) or through the tunnel platformctl opens automatically using your cluster credentials. See API authentication.
How much of this can I do from the command line?
Agents and functions: everything — deploy, invoke, logs, secrets, delete. The four service groups (serverless, pubsub, memorystore, vectordb) are mostly read-only in the CLI: you can list, get, and (for Pub/Sub) publish and pull, but creating and deleting an index, an instance, a topic, or a service is done in the console or over the API. See the CLI overview.
Projects, access, and identity
What's the difference between an organization, a project, and a grant?
An organization owns projects and users. A project is the workspace everything you create lives in — agents, functions, secrets, indexes, topics — with its own quota and its own member list. A grant is the role (member or admin) that gives one person or one machine access to one project. Access is never inherited just because you are in the same organization; someone has to grant it. See projects and access.
Why do I get 404 not found instead of 403 forbidden?
Because a 403 would confirm that the thing exists. If you hold no grant on a project, everything under it answers 404 — so nobody can map out other tenants' projects by probing for permission errors. You only see 403 once you already have some access but lack the role for that specific action. See troubleshooting.
Can Crusoe staff read my agents, secrets, or conversations?
Not silently. Platform admins hold authority over the project object (rename, delete, membership) and no authority at all over its contents. To reach your data, a platform admin has to take a break-glass grant: they must write a reason, it appears in your project's member list and audit log, and it expires on its own — 4 hours by default, 24 hours maximum. See break-glass and audit.
How do I give a CI pipeline access without sharing my password?
Create a service account in the project — a machine identity that holds a project role just like a person — and mint an API key for it. Store the key as CAI_TOKEN in your CI secrets. The key's secret is shown exactly once, and a service-account key can never create more keys or accounts, so a leak is contained and revocation actually works. See service accounts and API keys.
I lost an API key / invitation link. Can I get it back?
No. Key secrets, temporary passwords, MemoryStore passwords, and invitation tokens are shown exactly once, because only a hash is stored. Revoke the old one and create a new one — that is a two-minute job by design.
How long does a sign-in last?
12 hours. Session tokens are stateless, which means signing out (or having your account deleted) does not kill a token that is already issued — it stops the next sign-in, not the current one. There is no multi-factor authentication yet. See known issues.
Agents
Which agent frameworks can I use?
Three, all first-class: ADK (Google's Agent Development Kit), LangGraph, and CrewAI. Your entry file decides which: agent.py exporting root_agent, graph.py exporting a compiled graph, or crew.py exporting crew. Once deployed, all three answer the same HTTP contract, so callers never need to know which you picked. See Agent Engine overview.
How does my agent remember what was said earlier in the conversation?
Through the session. Every call carries a session_id; the platform stores that conversation's history and replays it to the model on each turn. Reuse the id and the agent has context; change it and you have started a new conversation. If you omit the id, the platform mints one and returns it — save it. See sessions.
What's the difference between sessions and memory?
A session is one conversation and disappears from the model's view the moment you use a different id. The memory bank is long-term: you explicitly memorize a session, which distills it into searchable storage that every future conversation with that agent can find. Sessions are automatic; memory is a deliberate act. See memory.
Is my memory bank private to me?
No — and this matters. The memory bank belongs to the agent, not to a caller. Anything memorized can be retrieved by anyone who later talks to that agent. That is exactly why memorize always requires authentication even though invoking does not. Don't memorize anything one caller shouldn't be able to read back.
Can anyone call my agent?
By default, yes — invoking is an open data plane, so an agent behaves like a public HTTPS endpoint. Managing it (deploy, logs, secrets, delete) always requires a credential. If invoke must be closed too, ask your administrator to turn on the platform-wide setting that requires authentication to invoke. Do not put anything sensitive behind an open alpha data plane. See invoke.
How do I change the model, or use my own model credit?
The model name comes from an environment variable, so a redeploy is enough to move — prefer reading it from the platform rather than hardcoding a model name in your code. To bill inference to your own credential instead of the shared platform key, set the agent's own key:
platformctl secrets set my-agent MODEL_API_KEY=sk-...
That rolls a new revision, and the agent picks it up on its next cold start. See secrets and env.
Why did my change not take effect?
Because revisions are immutable snapshots. Changing code, environment variables, secrets, or compute settings creates a new revision — the running one never changes. New revisions serve from the next cold start. If you moved traffic to an older revision, note that this pins serving only: the stored source is untouched, so the next deploy builds forward and supersedes the pin. See traffic and revisions.
Can I put a chat widget on my own website?
Yes. Enable the embed widget on the agent, add your site to the allowed-domains list, and paste one script tag. Visitors chat anonymously; each conversation resumes across page loads. Leaving the allowed-domains list empty means any website can embed your agent — always list your origins. See embed chat.
Compute: agents, functions, and services
Agent, function, or serverless service — which do I want?
| You have | Use | Why |
|---|---|---|
| Python agent code (ADK / LangGraph / CrewAI) | Agent | Sessions, memory, tools, and a model are wired in for you |
One handle(event) file in Python, Node.js, Go, or Ruby | Function | Smallest possible unit; no container to build |
| A container image you already have | Serverless service | Any language, any framework, full control of the process |
All three scale to zero and cold-start on the next request.
Can I use my own domain name?
Not yet. Published workloads get https://<name>-<project-short>.apps.codyhill.dev, and the hostname is computed for you — a custom hostname sent to the API is stored but ignored. See public endpoints and domains.
Does "internal" mean "authenticated"?
No, and this is a sharp edge worth internalizing. An unpublished service is not on the internet, but it is not authenticated either — any workload that can reach the platform's internal gateway can call it. If a service needs to know who is calling, it must check that itself.
Can I run a function on a schedule, or on a Pub/Sub message?
Not as a function. Functions are HTTP-triggered (and accept CloudEvents). Schedules, object-store events, and Pub/Sub sources are attached to serverless services as triggers. See HTTP and events and serverless overview.
How do I read logs from something that already scaled to zero?
Live logs need a live instance, so an idle workload returns a friendly message rather than an error. Use persisted history instead:
platformctl logs my-agent --history
History survives scale-to-zero and revision rollouts, and is retained for 14 days by default. See logs.
Where are my request-rate and latency charts?
There aren't any. The platform reports live values — instances running, revisions, readiness, sandbox pool state, MemoryStore memory and hit rate — but stores no time-series history, and says so in each response. Point-in-time truth, no invented graphs. See known issues.
Data services
Does VectorDB create embeddings for me?
No. You bring your own vectors. VectorDB stores them, searches them, and filters on the JSON payload you attach; turning text into numbers is your model's job. Agents get this wired up already through the memory bank. See VectorDB overview.
I picked the wrong number of dimensions. Can I change it?
No. dimensions, distance, shards, on_disk, and quantization are fixed when the index is created — existing points cannot be re-embedded, so a different width is a new index, not an edit. Only replicas and payload placement can change. Create a new index and re-ingest. See collections and points.
Can I reach MemoryStore, VectorDB, or Pub/Sub from outside the platform?
Partly, and the caveats are real. Optional external endpoints terminate at a gateway firewalled to your Crusoe VPC — reachable from your own VMs, not from the public internet. MemoryStore's rediss:// route works. Pub/Sub's external route currently proves connection and topic lookup only; produce and consume still need the in-cluster address. VectorDB's per-project external token is coded but off by default. See known issues.
Are there backups?
No. Deleting a VectorDB index destroys every vector in it; deleting a MemoryStore instance destroys its volume. Neither is recoverable and there are no snapshots. MemoryStore instances are single-node — persistence (on by default) survives a restart with roughly a one-second loss window, but there is no replica and no failover. Keep the source of truth somewhere you control.
Why did my published Pub/Sub message vanish?
Because a message is retained only while some subscription still owes an acknowledgement. Publishing to a topic with no subscriptions succeeds and returns an id, then the message is reclaimed. Create the subscription before you publish. See topics and subscriptions.
Why is my Pub/Sub quota full when all my topics are empty?
The storage budget is spent by claim, not by use: a topic reserves its whole max_bytes the instant it exists. Consuming messages never frees budget — deleting a topic, or lowering its max_bytes, does. See publish and consume.
Will I get every message exactly once?
No — delivery is at-least-once. A message can arrive twice (for example, if an acknowledgement is lost). Write consumers that can safely see the same message again: check an id, or make the operation idempotent.
Security and secrets
Where should I keep an API key my agent needs?
In the project secret store, then bind it to an environment variable on the agent and apply the binding. Storing is versioned, listing never shows values, and the only call that returns a value is an explicit, admin-only, audited reveal. See manage secrets.
I bound a secret but the agent doesn't see it
Binding records the rule; applying delivers it. Nothing reaches the agent until you apply, which reads the values, writes them onto the agent, and rolls a new revision that takes effect on the next cold start. Unbinding is the opposite — it takes effect immediately, because revoking access should never wait.
Can I read a secret back to check it?
Only through reveal, which requires the project admin role and is recorded in the audit log with your identity, the version, and the time. If the audit record cannot be written, the reveal is refused rather than performed unlogged. See break-glass and audit.
Is code my agent runs able to steal my credentials?
Model-generated Python (run_python) runs in a single-use pod with no credentials, no cluster access, and no network except DNS, and the pod is destroyed after one snippet. Your own tool functions run in a one-use pod built from your agent's image but stripped of its credentials. See security and limits.
Limits, cost, and expectations
What are the limits I'm most likely to hit?
Uploads: 100 MiB through the CLI, 32 MiB through the console. Lists: 50 per page by default, 200 maximum. Invoke bodies: 1 MiB, with a 60-second timeout. Function event bodies: 8 MiB. Sandbox snippets: 20 seconds. Project defaults: 50 running instances and a 1 GiB Pub/Sub budget. The full table is on the limits reference.
Which regions can I deploy to, and what's the SLA?
Neither exists yet. This is a single alpha deployment with no region selection and no published service-level agreement or support commitment. Compare that honestly against the big clouds before you put production traffic on it — see how we compare to AWS and the service mapping.
How do I know what changed in my project, and who changed it?
Every state change is written to the project's append-only audit log, readable by every member of the project — including break-glass grants taken by platform staff. It pages newest-first in the console. There is no export or date-range filter yet. See quotas and audit.
Something is broken and it isn't on any of these pages. What now?
Grab the request_id from the error body (or the console's error toast) and report it with what you were doing. If the behavior isn't listed in known issues or on the troubleshooting page, it is a real bug and we want to hear about it.