> ## Documentation Index
> Fetch the complete documentation index at: https://alchemy.getgalaxy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Alchemy

> Install Alchemy on Kubernetes with the Helm chart and the published server, host and runtime images, and verify their attestations.

Kubernetes with Helm is the recommended way to run Alchemy. Hosts need
`/dev/kvm`, so they run on bare-metal nodes or on VMs with nested
virtualization. The server runs anywhere. To run Alchemy on your own machine
from source, follow the [Quickstart](https://alchemy.getgalaxy.io/pages/get-started/quickstart.md)
instead.

## Helm chart

Every release publishes the chart to `oci://ghcr.io/galaxy-io/charts/alchemy`.
The chart's version matches the release, and it deploys the server and host
images of that same version.

Alchemy needs a PostgreSQL DSN, a NATS URL and an encryption key for tenant
secrets. Put them in a Secret and point the chart at it:

```sh theme={null}
kubectl create secret generic alchemy-runtime \
  --from-literal=PERSISTENCE_DSN='postgresql://USER:PASSWORD@HOST:5432/alchemy?sslmode=require' \
  --from-literal=NATS_URL='nats://nats.example.com:4222' \
  --from-literal=ENCRYPTION_KEY="$(openssl rand -base64 32)"

helm upgrade --install alchemy oci://ghcr.io/galaxy-io/charts/alchemy \
  --set existingSecret=alchemy-runtime
```

Without `--version`, Helm installs the newest release. NATS must have
JetStream enabled with file and memory storage and a `max_payload` above
8 MiB. See [Storage](https://alchemy.getgalaxy.io/pages/deployment/storage.md).

Before the hosts can schedule, label and taint the KVM nodes. The chart's
hosts select and tolerate `alchemy.getgalaxy.io/kvm=true` by default:

```sh theme={null}
kubectl label node <node> alchemy.getgalaxy.io/kvm=true
kubectl taint node <node> alchemy.getgalaxy.io/kvm=true:NoSchedule
```

[Kubernetes](https://alchemy.getgalaxy.io/pages/deployment/kubernetes.md) covers the chart in full,
including the vendored PostgreSQL and NATS for test clusters, and
[KVM nodes](https://alchemy.getgalaxy.io/pages/deployment/kvm-nodes.md) covers preparing the nodes.

## Container images

The images live under `ghcr.io/galaxy-io/alchemy`:

| Image | Purpose |
| - | - |
| `ghcr.io/galaxy-io/alchemy/server` | API, invoke endpoint and the embedded web UI |
| `ghcr.io/galaxy-io/alchemy/host` | Host process, Firecracker and its jailer, a guest kernel and the supervisor |
| `ghcr.io/galaxy-io/alchemy/runtime/python:3.13` | Python runtime with the Arrow library |
| `ghcr.io/galaxy-io/alchemy/runtime/node:24` | Node runtime for TypeScript and JavaScript functions |
| `ghcr.io/galaxy-io/alchemy/runtime/static:13` | Distroless Debian 13 for a function that is one static binary |
| `ghcr.io/galaxy-io/alchemy/runtime/go:1.27` | Runs a Go function built from source, which `go:1.27-build` compiles |
| `ghcr.io/galaxy-io/alchemy/runtime/rust:1.99` | Runs a Rust function built from source, which `rust:1.99-build` compiles |

The server and host images are tagged with the release version, such as
`0.0.1`, and with `sha-<commit>`. Use the same version for both. The chart
defaults their tags to its own app version.

The runtime images are published apart from releases, whenever one changes
on `main`. Each carries its language version as its tag, plus that version
with a hash of the runtime's source tree. Point the chart's
`runtimes.imagePrefix` at a registry of your own to serve the runtimes from
there. See [Runtimes and builds](https://alchemy.getgalaxy.io/pages/concepts/runtimes-and-builds.md).

## Verify a release

The chart and every published image carry a build provenance attestation.
Verify them with the GitHub CLI:

```sh theme={null}
gh attestation verify --owner galaxy-io oci://ghcr.io/galaxy-io/charts/alchemy:<version>
gh attestation verify --owner galaxy-io oci://ghcr.io/galaxy-io/alchemy/server:<version>
gh attestation verify --owner galaxy-io oci://ghcr.io/galaxy-io/alchemy/host:<version>
```

## Next steps

* [Deployment overview](https://alchemy.getgalaxy.io/pages/deployment/overview.md) to choose how to
  size and run the server and hosts.
* [Configuration](https://alchemy.getgalaxy.io/pages/deployment/configuration.md) for every
  environment variable the server and host read.
* [Authentication](https://alchemy.getgalaxy.io/pages/deployment/authentication.md) to put the API
  behind an identity provider.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.