# Aetherfy

> Aetherfy is a Qdrant-compatible vector database and an agent compute platform
> (push-to-deploy agents, scheduled tasks) behind one control plane.

Region availability is plan-scoped: Free and Starter run in a single region chosen by your
first resource; multi-region replication begins at the Performance tier.

Machine-readable artifacts: https://docs.aetherfy.com/docs-manifest.json (catalogue with a rawUrl per page),
https://docs.aetherfy.com/openapi.json (vector API), https://docs.aetherfy.com/agents-openapi.json (agent control plane —
a SEPARATE API: different host, request budget and error envelope),
https://docs.aetherfy.com/aetherfy-yaml.schema.json, https://docs.aetherfy.com/errors.json.
The clean markdown source of any page is at https://docs.aetherfy.com/raw/<route>.md

MCP server: https://docs.aetherfy.com/api/mcp — remote, public, read-only, Streamable HTTP.
Tools: search_docs, get_doc_page, get_manifest, get_aetherfy_yaml_schema, list_errors.
It reads exactly the artifacts above, so the two can never disagree.

## Agent compute

- [Agent compute overview](https://docs.aetherfy.com/agents): Aetherfy agent compute runs your code either as a long-lived service or as a task that runs once and exits, deployed from the afy CLI or a linked GitHub repository and configured by a single aetherfy.yaml file.
- [aetherfy.yaml reference](https://docs.aetherfy.com/agents/aetherfy-yaml): Field reference for the Aetherfy agent file aetherfy.yaml — every field's type, default and allowed values, why spawn.workers lists the agents it may spawn, what a field you leave out means, archive and lockfile requirements, and how an unknown field is refused.
- [Agent REST API](https://docs.aetherfy.com/agents/api): Index of the Aetherfy agent control-plane REST API at https://agents.aetherfy.com/api/v1 — base URL, bearer authentication, the error envelope and how it differs from the vector API, rate limiting, and the full route table across all sixty-one endpoints.
- [Account and usage API](https://docs.aetherfy.com/agents/api-account): REST reference for Aetherfy account-level control-plane routes — reading the authenticated identity and its live plan limits, reading per-agent machine lifecycle events, and connecting a GitHub account.
- [Deployments API](https://docs.aetherfy.com/agents/api-deployments): REST reference for Aetherfy deployments — uploading a code archive to deploy, listing and reading deployment records, rolling back, cancelling an in-flight build, reading a run's payload and its result, waiting for a run to finish, and linking an agent to a GitHub repository.
- [Agent lifecycle API](https://docs.aetherfy.com/agents/api-lifecycle): REST reference for the Aetherfy agent lifecycle — create, list, read, update and delete agents, stop, start, archive and restore them, read live machine status, and export an agent's aetherfy.yaml.
- [Runs, schedules and spawns API](https://docs.aetherfy.com/agents/api-runs): REST reference for running Aetherfy agents on demand — triggering a run, listing run history with keyset pagination and whether each run returned a result, pausing and resuming a scheduled task, spawning a worker agent with a payload, and querying runtime logs.
- [Secrets API](https://docs.aetherfy.com/agents/api-secrets): REST reference for Aetherfy secrets — setting and rotating an agent's encrypted environment secrets, listing their keys, deleting them, and the workspace-scoped equivalents shared across every agent in a workspace.
- [Workspaces and regions API](https://docs.aetherfy.com/agents/api-workspaces): REST reference for Aetherfy workspaces and regional placement — creating, renaming and deleting workspaces, listing their agents, changing a workspace's region set, moving a collection between workspaces, region-change usage, and polling the long-running operations.
- [Custom Dockerfile runtime](https://docs.aetherfy.com/agents/dockerfile): How runtime dockerfile works on Aetherfy — you supply the whole container and Aetherfy puts its supervisor in front of your command, the port your server listens on, what the archive must contain, what validation blocks versus warns, and the plan tiers that allow it.
- [GitHub integration](https://docs.aetherfy.com/agents/github): How to connect the Aetherfy GitHub App, link a repository and branch to an agent, use --root-dir to keep several agents in one repository, and what happens on each push, including the cases Aetherfy deliberately ignores and how a push that arrives during a deploy waits for it.
- [Running and managing agents](https://docs.aetherfy.com/agents/managing): How to run an Aetherfy agent on demand with afy run, pause and resume its schedule, understand skipped and missed occurrences, and choose between stopping, archiving, and deleting an agent.
- [Agent compute metrics](https://docs.aetherfy.com/agents/metrics): What every figure on the Aetherfy agent compute dashboard means, which of the two sources it comes from, why an absence is rendered as "no data" rather than zero, and why the count of agents with activity is not the count of agents you have deployed.
- [Node.js and Bun services](https://docs.aetherfy.com/agents/node-and-bun): The export shapes a Node.js or Bun service agent can give Aetherfy — an Express app, a Hono app or a bare fetch handler, and a WebSocket server exported beside the app — each with a complete project you can deploy as is, and the one shape Aetherfy refuses.
- [Deploy an agent](https://docs.aetherfy.com/agents/quickstart): Deploy a working Aetherfy agent in one sitting — afy login, write the aetherfy.yaml and entrypoint, ship it with afy deploy, which offers to create the agent, then read the output with afy logs; includes the service contract, where your entrypoint exports an app object for Aetherfy to serve.
- [Rollback](https://docs.aetherfy.com/agents/rollback): How to return an Aetherfy agent to an earlier deployment with afy rollback — reading deployment history, the bare-integer version argument, which versions are valid targets, and when a rollback re-deploys the exact image or rebuilds the version from its stored source.
- [Runs and logs](https://docs.aetherfy.com/agents/runs-and-logs): Reference for Aetherfy run history and logs — listing runs with afy runs, the run and deployment states, agent status values, every afy logs flag, and the 7-day retention and per-line caps Aetherfy enforces.
- [Scheduled tasks](https://docs.aetherfy.com/agents/scheduled-tasks): Reference for Aetherfy scheduled tasks on job and service agents — the schedule field in aetherfy.yaml, the 5-field UTC cron expression format, the expressions Aetherfy rejects, the 5-minute minimum interval, what a run costs before your code starts, and changing or removing a schedule.
- [Secrets](https://docs.aetherfy.com/agents/secrets): Reference for Aetherfy agent secrets — agent-scoped and workspace-scoped values injected as environment variables, key naming rules, the reserved AETHERFY_ prefix, and the rule that a machine keeps the values it was created with, so a change takes effect on the next deploy.
- [The task contract](https://docs.aetherfy.com/agents/task-contract): How code runs on Aetherfy as a type job task — a plain script, exit codes deciding the outcome, logs, payload and result files, overlapping runs on machines of their own, at-most-once execution, the 60-minute backstop — and the POST /aetherfy/run route a type service agent answers.
- [An agent that uses memory](https://docs.aetherfy.com/examples/agent-with-memory): A complete Aetherfy agent in Python and Node that writes and searches memories, with its aetherfy.yaml, the afy deploy command, and the environment variables every agent machine receives automatically.
- [Spawn patterns](https://docs.aetherfy.com/examples/spawn-patterns): Three Python and Node patterns for Aetherfy task agents that spawn other tasks — an independent assessor that checks an output against a rubric, a manager that fans out one task per account and aggregates, and a child whose progress its parent reads from the run's logs.

## CLI

- [Aetherfy CLI — install, authentication, and configuration](https://docs.aetherfy.com/cli): The Aetherfy CLI is a Go binary named afy, installed by an aetherfy.com install script, a release archive, go install of cmd/afy, or from source, updated by afy upgrade, authenticated with an afy_live_ API key, and configured through config.yaml, environment variables, and four global flags.
- [Aetherfy agent commands](https://docs.aetherfy.com/cli/agents): Complete reference for the Aetherfy CLI's agent verbs, which are its top-level commands — list, create in a workspace, delete, stop, start, archive, restore, cancel, status, update (name, workspace, description), access, diff, run, runs, and schedule pause/resume, with every flag and default.
- [afy init, deploy, deployments, redeploy, and rollback in the Aetherfy CLI](https://docs.aetherfy.com/cli/deploy): Reference for the Aetherfy CLI deployment commands — afy init creates or links an agent and writes aetherfy.yaml, the link file and its targets, afy deploy uploads to the linked agent, staging and production from one codebase, afy deployments, afy redeploy and afy rollback.
- [afy github — Aetherfy GitHub App and auto-deploy](https://docs.aetherfy.com/cli/github): Reference for afy github in the Aetherfy CLI — connect, disconnect, status, repos, link, and unlink, covering the several GitHub accounts one Aetherfy account can hold, the --branch and --root-dir flags, and the one-time webhook secret.
- [afy logs — Aetherfy agent log reference](https://docs.aetherfy.com/cli/logs): Reference for afy logs in the Aetherfy CLI — every flag including --tail, --follow, --since, --level, --stream and --run, the output line format, the server-side 1000-line cap, and the flags that --follow ignores.
- [afy secrets — Aetherfy agent and workspace secrets](https://docs.aetherfy.com/cli/secrets): Reference for afy secrets in the Aetherfy CLI — list, set, and delete agent-scoped or workspace-scoped secrets, the --workspace and --stdin flags, the AETHERFY_ reserved prefix, and the rule that agent secrets override workspace secrets.
- [afy spawn — starting an Aetherfy child agent from a parent](https://docs.aetherfy.com/cli/spawn): Reference for afy spawn in the Aetherfy CLI — the two required arguments, the mutually exclusive --payload, --payload-file and --stdin flags, the four spawn requirements, the output keys, and why spawned runs do not appear in afy runs.
- [afy collections, index, and points — Aetherfy vector commands](https://docs.aetherfy.com/cli/vectors): Reference for the Aetherfy CLI's vector commands, all run in a workspace — afy collections (list, get, create, update, delete, regions, region-limits, move, schema), afy index and afy points — with --json output and exit codes.
- [afy workspaces — Aetherfy workspace reference](https://docs.aetherfy.com/cli/workspaces): Reference for afy workspaces in the Aetherfy CLI — create, list, info, update (rename or describe), regions, delete, and agents, with the name rules, what a rename changes and what workspace deletion does and does not remove.

## Dashboard

- [Dashboard reference](https://docs.aetherfy.com/dashboard): A map of the Aetherfy dashboard at app.aetherfy.com — every sidebar area, what it is for, and the reference page that lists its labels, states and actions with their afy CLI and REST API equivalents.
- [Agents in the dashboard](https://docs.aetherfy.com/dashboard/agents): Reference for the Agents area of the Aetherfy dashboard — the agent inventory, one agent's deployments, logs, access and secrets, and the YAML configurator — with every status, badge and note it shows, and the afy CLI command and REST route behind each action.
- [Database in the dashboard](https://docs.aetherfy.com/dashboard/database): Reference for the Database area of the Aetherfy dashboard — collections by workspace, the vector explorer, schema, and placement (regions, workspace, name) — with every label it shows and the afy CLI and API equivalents.
- [Secrets in the dashboard](https://docs.aetherfy.com/dashboard/secrets): Reference for the Secrets area of the Aetherfy dashboard — adding, listing and deleting agent-scoped and workspace-scoped secrets, what each label means, when a change reaches a running agent, and the afy CLI and REST equivalents.
- [Settings in the dashboard](https://docs.aetherfy.com/dashboard/settings): Reference for the Settings area of the Aetherfy dashboard — identity and account deletion, API keys, plan and payment, the developer quick start and the GitHub integration — with every label each tab shows and the afy CLI and REST equivalents.
- [Usage and billing in the dashboard](https://docs.aetherfy.com/dashboard/usage-and-billing): Reference for the Aetherfy dashboard's usage meter and its Plan & Payment settings — plan and subscription status, agent quota, the period's usage, the spend limit, plan changes, cancellation and invoices — with every label they show and what each means.
- [Workspaces in the dashboard](https://docs.aetherfy.com/dashboard/workspaces): Reference for the Workspaces area of the Aetherfy dashboard — creating, renaming and deleting workspaces, a workspace's regions, the agents that live there or have access, its secrets and collections — with every label it shows and the afy CLI and REST equivalents.

## Platform

- [Aetherfy Documentation](https://docs.aetherfy.com/): Aetherfy is a Qdrant-compatible vector database and a push-to-deploy agent compute platform behind one control plane, documented here for both Python and JS/TS.
- [Using AI with Aetherfy](https://docs.aetherfy.com/platform/ai): How to point a coding agent at the Aetherfy documentation — the remote MCP server at docs.aetherfy.com/api/mcp and its five tools, setup for Claude, Claude Code, ChatGPT, Codex, Cursor, VS Code, Windsurf and Gemini CLI, the machine-readable entry points, and a rules snippet for the rest.
- [API keys](https://docs.aetherfy.com/platform/api-keys): Reference for Aetherfy API keys — formats, one-time reveal, per-plan limits, rotation, the agent-injected keys and the routes and workspaces they reach, and the auth error codes.
- [Billing and spend caps](https://docs.aetherfy.com/platform/billing): Reference for Aetherfy billing — tier prices and inclusions, what counts as usage, the one-month offset between base fee and usage charges, self-service spend caps, and the two distinct stages of growth freeze and machine pause when a limit is reached.
- [Limits](https://docs.aetherfy.com/platform/limits): The Aetherfy platform limit index — per-plan quotas for agents, memory, regions, collections, keys, workspaces and storage, the per-plan cap on task runs in flight at once, the separate vector and control-plane rate limits, and fixed task-duration and log-retention limits.
- [Regions and replication](https://docs.aetherfy.com/platform/regions): How Aetherfy places data and compute across us-east-1, eu-central-1 and ap-southeast-1, how a workspace owns its regions, and how asynchronous multi-region replication behaves on the Performance plan and above.
- [Workspaces](https://docs.aetherfy.com/platform/workspaces): Reference for Aetherfy workspaces — where every agent and collection lives, the default workspace, shared secrets, a workspace per customer with grants, closing a customer, why the memory SDK's threads collection never moves, per-plan limits and the error codes.

## Vector database

- [SDK examples](https://docs.aetherfy.com/examples): Index of the Aetherfy SDK cookbook, with the install line, the AETHERFY_API_KEY setup, and the client construction that every example on this site starts from.
- [Batch upsert and pagination](https://docs.aetherfy.com/examples/batch-and-pagination): Complete Python and JavaScript examples of batched upserts into Aetherfy plus both pagination styles, the scroll_iter/scrollIter generators and the manual scroll cursor, with the batch-size bounds and the TypeScript types each style uses.
- [Collection lifecycle and payload schema](https://docs.aetherfy.com/examples/collection-lifecycle): Complete Python and JavaScript examples for listing, checking, inspecting and deleting Aetherfy collections, plus payload mutation and the get/set/analyze schema calls with their enforcement modes.
- [Bring your own embeddings](https://docs.aetherfy.com/examples/embeddings): Aetherfy does not generate embeddings; complete Python and JavaScript examples show the provider-agnostic embed seam that feeds vectors into upsert, search and the memory API, and how to match the collection dimension.
- [Filtered search](https://docs.aetherfy.com/examples/filtered-search): Complete Python and JavaScript examples of Aetherfy filtered vector search using the must, should and must_not vocabulary, including how each SDK spells the exclusion clause.
- [First collection - upsert and search](https://docs.aetherfy.com/examples/first-collection): Complete Python and JavaScript examples that create an Aetherfy collection, upsert points with payloads, and run a vector search, including the point-id rules and the returned SearchResult shape.
- [The memory API](https://docs.aetherfy.com/examples/memory-api): Complete Python and JavaScript examples of the Aetherfy memory layer - namespaces for facts, threads for conversations, how each is stored, their shared read surface, reserved metadata keys and the vector requirement.
- [Retrieve, delete and count](https://docs.aetherfy.com/examples/retrieve-delete-count): Complete Python and JavaScript examples for fetching Aetherfy points by id, deleting by id list or by filter, and counting points, including the divergent exact default between the two SDKs.
- [Quickstart — your first vector search](https://docs.aetherfy.com/quickstart): Create an Aetherfy API key, install the Python or JS/TS SDK, create a collection, upsert points, and get search results back in one sitting.
- [Vector database overview](https://docs.aetherfy.com/vectors): The Aetherfy vector database is a Qdrant-compatible service reached over REST at https://vectors.aetherfy.com or through the Python and JavaScript SDKs, authenticated with an afy_ API key.
- [REST API reference](https://docs.aetherfy.com/vectors/api): Every REST route of the Aetherfy vector API at https://vectors.aetherfy.com/api/v1, each under a workspace named by name or id — collections and rename, points, payload, aliases and the zero-downtime re-index, schema, regions, and the unsupported Qdrant endpoints.
- [Errors](https://docs.aetherfy.com/vectors/errors): The Aetherfy vector API error envelope, every stable error code with its HTTP status and retryability, and the exception classes the Python and JavaScript SDKs raise for each.
- [Filtering](https://docs.aetherfy.com/vectors/filtering): Payload filter syntax for the Aetherfy vector database — must, should and must_not clauses with match and range conditions, forwarded verbatim to Qdrant, including how each SDK spells the exclusion clause.
- [Limits](https://docs.aetherfy.com/vectors/limits): Enforced limits of the Aetherfy vector database — per-request caps on search, retrieve, delete and upsert, per-plan request rate, collection and storage caps, the fixed 60-second rate-limit bucket, and per-replica storage accounting.
- [SDK reference](https://docs.aetherfy.com/vectors/sdk): Reference for the Aetherfy vector SDKs — the aetherfy-vectors Python and JavaScript packages, their client constructors, complete method surface, model shapes, point ID rules, and the per-language divergences that change results.
- [Search tuning](https://docs.aetherfy.com/vectors/search-tuning): How to tune query-time search behaviour in the Aetherfy vector database with search_params / searchParams, including hnsw_ef, cache-key behaviour, and how both SDKs reject unknown options — plus what to rule out first when results are irrelevant rather than merely imprecise.
- [Usage and metrics](https://docs.aetherfy.com/vectors/usage-and-metrics): The two Aetherfy analytics reads — plan usage and measured request telemetry — including the histogram-bound percentiles, the coverage rule that separates a real zero from an unobserved one, and the null sentinels both endpoints use.