Core Concepts#

These are the concepts that matter most when you build on the current Apothic runtime.

App#

An App is the packaging unit you deploy.

It collects:

remote functions
services
schedules
class-based resources
sandboxes
local entrypoints

When you deploy an app, Apothic creates a deployment that can be inspected, watched, stopped, or deleted later.

Function#

@app.function(...) is the core remote execution primitive.

Use it for:

CPU or GPU workloads
background processing
request/response calls
retried or batched jobs

A function can be invoked synchronously with remote() or as a job with spawn().

Job#

A job is a concrete execution instance of a function call.

Jobs are useful because they are observable:

you can read status
you can fetch logs
you can wait for completion
you can watch typed job events

This is what makes Apothic useful for both background processing and live operator workflows.

Deployment#

A deployment is the current live version of an app.

Deployments matter because they separate:

authoring code
packaging and registration
the currently live version of a service or function set

You can also watch deployment event streams, which is useful for automation and operations.

Services#

Not every workload is a background job. Apothic also supports live service shapes:

@app.endpoint(...)
@app.asgi(...)
@app.fastapi_endpoint(...)
@app.wsgi_app()
@app.web_server(...)

Choose the smallest one that matches your application.

Classes and sandboxes#

Not every workload fits a stateless request model.

@app.cls(...) gives you named or ephemeral stateful instances with:

constructor arguments
@enter() and @exit() lifecycle hooks
@method()-decorated remote methods
serializable handles for reattachment

app.sandbox(...) uses the same persistent-instance model, but exposes:

filesystem operations
command execution
named sessions
resumable handles

Use classes when your abstraction is an object. Use sandboxes when your abstraction is a workspace.

Images and execution environments#

Every function or service also declares an execution image.

At the client layer that usually means:

Image.debian_slim(...)
Image.from_registry(...)
Image.from_dockerfile(...)
pip_install(...)
uv_pip_install(...)
apt_install(...)
env(...)
run_commands(...)
local build-context inclusion for files, directories, or Python source

This is what lets you move from a trivial CPU function to a GPU-backed model service without changing the higher-level Apothic resource model.

For simple image.base cases, the current runtime can often execute the base image directly. If a Linux base image does not already contain a suitable Python runtime, the runtime can fall back to a managed CPython and later reuse an optimized derived image when needed.

Storage and secrets#

Apothic now has multiple storage lanes rather than one generic mount type.

Use:

portable named volumes for runtime-managed durable storage
vast_local volumes for fast host-local persistent storage
CloudBucketMount(...) for explicit S3-compatible bucket mounts
Secret records for credentials and tokens

Important distinction:

portable storage trades some hot-path performance for flexibility
vast_local trades portability for speed and host affinity

That host affinity is part of the contract, not an incidental implementation detail.

Shared state#

The runtime includes named shared primitives for coordination.

Queue#

Use Queue when work should be consumed over time.

It supports:

put(...)
blocking get(...)
claims
acknowledgements
lease renewal and release
retry and dead-letter helpers
watch streams

Dict#

Use Dict when multiple workers need shared key/value state.

It supports:

point reads and writes
leases on individual keys
compare-and-set updates
locks
leader election
watch streams

Together, Queue and Dict let you build distributed worker coordination without writing your own control plane.

Capacity and placement#

Placement is no longer limited to a few scalar fields.

You can still use convenience options such as:

gpu
gpu_count
min_vram_gb
geolocation
max_cost_per_hour_usd

But you can also use offer_filters for structured comparison filters against capacity metadata:

eq
neq
gt
lt
gte
lte
in
notin

The runtime uses that filter model both when it searches for new capacity and when it decides whether an existing worker can be reused.

Use the named fields when they are readable enough. Use offer_filters when you need ranges, inclusion tests, or less-common metadata fields.

Watches and snapshots#

Many runtime resources support watch streams.

That includes:

jobs
apps
deployments
queues
dictionaries

When snapshot=True is available, the stream starts with current state and then continues into live updates.

This pattern is useful for:

operator dashboards
long-running automation
worker orchestration
progress-aware UIs

Generated implementations with `liv`#

Apothic can materialize generated Python implementations before deploy through @apothic.liv(...) and LivConfig.

The current model is deploy-time freeze:

generation happens before deploy
the generated module is packaged with the app
the remote worker executes the frozen generated code

Runtime architecture#

The public Apothic runtime is now the native control plane at https://run.apothic.ai.

At a high level:

the control plane runs on Fly
durable runtime metadata lives in SurrealDB
user compute runs on on-demand workers rather than on the control-plane app
workers establish outbound sessions back to the runtime

That is why Apothic can expose one unified developer surface even though services, jobs, sandboxes, and mounted storage all have different execution paths underneath.

Authentication and account scope#

Runtime calls are associated with an Apothic account through API keys and auth headers.

That account context flows into:

resource ownership
billing attribution
account-scoped caching and coordination primitives where appropriate

Billing and balance#

Runtime work is billable against your Apothic account balance.

At a high level:

you fund your account through the website billing flow
runtime resources are attributed to your account
jobs and long-lived services can settle charges against that balance

This is why authentication is not just about access control. It also defines who owns and pays for the runtime resources being created.

Developer workflow#

A typical workflow looks like this:

define an app
authenticate with an Apothic API key
create any secrets or volumes the app needs
deploy it
invoke a function, service, class instance, or sandbox
watch the resulting job or deployment
clean up older deployments when appropriate