FAQ
Each answer here is checked against what Geass does today. Where a question has a longer page behind it, the answer links to it.
The basics
Section titled “The basics”Is Geass a managed service?
Section titled “Is Geass a managed service?”No. Geass is software that runs on servers you own or rent. Nobody operates those servers for you, and the project does not host a service. The license forbids offering Geass to third parties as a hosted or managed service. See What is Geass.
Do I need to know Kubernetes?
Section titled “Do I need to know Kubernetes?”Not to use it. You create projects, services and databases in the dashboard. Underneath, Geass runs on K3s, so when something breaks you may read logs or objects with kubectl, which on the control plane is sudo k3s kubectl. The docs give you the commands. See How Geass works.
Is there a command-line tool or an MCP server?
Section titled “Is there a command-line tool or an MCP server?”Yes, both, in one program called geass. The command line lists, creates, deploys, scales and rolls back services, reads logs and metrics, edits variables and calls any API endpoint. geass mcp runs the same operations as a Model Context Protocol server for AI agents. They are separate from the installer: you install geass on your own machine, after the cluster exists. See Command line, MCP server for AI agents, CLI commands and MCP tools.
Can I automate Geass or let an AI agent run it?
Section titled “Can I automate Geass or let an AI agent run it?”Yes. Everything the command line and the MCP server do goes through the versioned /api/v1 API with an API token, so a script, a CI job or an agent has exactly the rights of its token. For a script, install geass, set GEASS_URL and GEASS_TOKEN, and run commands such as geass deploy web --wait: it exits with 5 if the deploy fails and 6 if it times out. For an agent, run geass mcp and give it its own token. A Read only, with logs token lets an agent watch without being able to change anything, and the agent is shown only the tools that token may use. A project token limits a deploy job to one environment of one project. See Users and API tokens and the REST API.
How does the command line sign in?
Section titled “How does the command line sign in?”You run geass login --url https://geass.example.com. It prints a short code and the address of an approval page, /device on your dashboard. You open it, signed in as an admin, check that the code is the one in your terminal, choose what the command line may do and for how long, and approve. Geass then hands the command line a token once and it is saved on your machine. No password is typed into the terminal, and only a person signed in with a password can approve: a token cannot. See Sign in to the dashboard.
Does Geass send data to its authors?
Section titled “Does Geass send data to its authors?”No. The repository contains no telemetry or analytics code. Geass does make outbound requests that you should expect: the installer downloads from GitHub and get.k3s.io; the cluster downloads Helm charts and container images from public hosts; when you connect them, the operator calls the GitHub, Cloudflare, AWS and PlanetScale APIs; it asks api.ipify.org, then ifconfig.me, for the server’s public IP only when no node reports one and it needs the address for dashboard DNS; and cert-manager talks to Let’s Encrypt once the certificate issuer exists. The geass command line talks only to the Geass address you give it. See Requirements.
Which license does Geass use, and can I use it at work?
Section titled “Which license does Geass use, and can I use it at work?”The Elastic License 2.0, in the LICENSE file. You may use, copy, modify and deploy Geass for yourself or your organization. You may not provide it to third parties as a hosted or managed service that gives them access to a substantial set of its features. You must keep its notices. It is source-available, not open source in the Open Source Initiative’s sense. For anything unclear, read the license or ask a lawyer.
Servers
Section titled “Servers”Do I need one server or several?
Section titled “Do I need one server or several?”One is a complete install: the installer builds a K3s server and runs everything on it. You add capacity by joining workers over SSH. See Add servers.
Is there a highly available control plane?
Section titled “Is there a highly available control plane?”No. There is one K3s server and one operator. If that server goes down, the dashboard and everything the operator does stop until it returns. The one high availability feature is a Postgres database that runs as three instances on three nodes, and Geass only lets one start when the cluster has at least three healthy nodes. See High availability.
Can I install Geass on a machine that already runs K3s or Kubernetes?
Section titled “Can I install Geass on a machine that already runs K3s or Kubernetes?”Not alongside it. The installer uninstalls an existing K3s before it installs its own, with no confirmation. Geass also depends on parts that K3s bundles: its Helm controller and the Traefik ingress. The installer is the only documented way to set it up. See Install Geass.
Which providers and operating systems work?
Section titled “Which providers and operating systems work?”Any Linux server on amd64 or arm64 that K3s supports, from any provider. The installer checks only that it runs on Linux, on one of those two architectures, with enough memory and disk. Geass does not create servers at any provider: you bring them. A cluster whose nodes are at different providers is experimental. See Requirements and Multi-provider clusters.
Why does the installer reject my 2 GB server?
Section titled “Why does the installer reject my 2 GB server?”It requires at least 1700 MiB of MemTotal, as the kernel reports it. The kernel reports less than the size on the plan, but a “2 GB” machine reports about 1.7 to 1.95 GiB, so it passes; a 1 GB machine does not. Check with grep MemTotal /proc/meminfo. The installer’s 2 GiB and 10 GiB are a floor: the add-ons it installs also use CPU, memory and disk. See Requirements.
Can I run it on a server without a public IP?
Section titled “Can I run it on a server without a public IP?”You can install it and use the dashboard through an SSH tunnel and kubectl port-forward. To publish services, Cloudflare Tunnel can carry traffic through cloudflared instead of open ports; it needs a Cloudflare account. Workers still need to be reachable over SSH from the control plane. See Sign in to the dashboard and Connect a domain.
What happens when the server reboots?
Section titled “What happens when the server reboots?”K3s runs as a service that starts at boot, and the operator and your workloads start with it. Data on volumes is on the disk and is still there.
Does it run on ARM?
Section titled “Does it run on ARM?”Releases include an arm64 installer, which carries an arm64 operator image. The add-ons come from upstream Helm charts.
Installing and upgrading
Section titled “Installing and upgrading”Does the installer set up the dashboard login?
Section titled “Does the installer set up the dashboard login?”No. A fresh install has no user and no password. You create the first user with a Kubernetes Secret and reach the dashboard through a tunnel. Geass generates no password. See Sign in to the dashboard.
How is the dashboard reached after the install?
Section titled “How is the dashboard reached after the install?”It is a ClusterIP Service, so only inside the cluster at first. Use kubectl port-forward for the first sign-in, then set a domain under Settings → Domain. See Sign in to the dashboard.
Do I need a domain?
Section titled “Do I need a domain?”Not to install, sign in or run a service: you can reach a service with kubectl port-forward. You need hostnames to publish services, to serve the dashboard over HTTPS, and to register the GitHub App. See Deploy your first app.
Is HTTPS automatic?
Section titled “Is HTTPS automatic?”Not unless you give it an email address. Geass gets certificates from Let’s Encrypt through cert-manager, and Let’s Encrypt wants a contact address for the account. Pass one to the installer as GEASS_ACME_EMAIL, or set spec.addons.certManager.acmeEmail on the cluster later, and Geass creates the letsencrypt-prod issuer that the Ingress objects it generates ask for. Without an address no certificate is issued. Ports 80 and 443 must also be open, because Let’s Encrypt validates a hostname over 80/tcp. With a Cloudflare Tunnel, Cloudflare serves HTTPS to visitors instead. See HTTPS certificates and Domains and TLS.
What does running the installer a second time do?
Section titled “What does running the installer a second time do?”It uninstalls K3s from that machine first, then installs a new cluster. That deletes the old cluster’s database: projects, services, secrets, users and tokens, and local volumes. It is a reinstall, not an upgrade. See Install Geass.
How do I upgrade Geass?
Section titled “How do I upgrade Geass?”There is no in-place upgrade yet. The options are a new server with the new release, a reinstall, or updating the operator from source. See Upgrade Geass.
How do I know which version I run?
Section titled “How do I know which version I run?”The cluster does not record it, and the dashboard shows no version. Note the release tag when you install. geass version prints the command line’s own version, and api v1 under it is the version of the API, not of the release.
Cloud accounts
Section titled “Cloud accounts”What does Geass need from my cloud accounts?
Section titled “What does Geass need from my cloud accounts?”Nothing to install or to deploy a service. Each account unlocks specific features:
| Account | Unlocks | What Geass needs |
|---|---|---|
| Cloudflare | DNS records for the dashboard and services, Cloudflare Tunnel | An API token with Account → Cloudflare Tunnel → Edit, Zone → DNS → Edit and Zone → Zone → Read |
| GitHub | Repository deploys, push-to-deploy, pull request environments | A GitHub App that Geass registers. The dashboard needs a public domain first |
| AWS | S3 buckets, database backups | An access key that can create and delete S3 buckets and objects, and create and delete IAM users with their keys and policy |
| PlanetScale | PlanetScale databases | A service token and the organization name |
AWS and PlanetScale credentials belong to one project. See Cloud connectors.
Does Geass create servers, or work with Google Cloud or Azure?
Section titled “Does Geass create servers, or work with Google Cloud or Azure?”No to both. Geass has no connector that creates machines, and no Google Cloud or Azure integration. A server at any provider can join as a node.
Data and backups
Section titled “Data and backups”Where is my data?
Section titled “Where is my data?”| Data | Where |
|---|---|
| Geass’s own state (projects, services, settings, secrets) | K3s’s embedded etcd, on the control plane’s disk |
| PostgreSQL, MySQL and SQLite data | Volumes on your nodes: Longhorn, replicated across up to three nodes, or K3s’s local-path storage on one node |
| Redis data | Memory only. Redis runs without persistence |
| In-cluster buckets | The MinIO server in the cluster |
| AWS S3 buckets and database backups | Your AWS account |
| Metrics and logs | Volumes on your nodes: 15 days of metrics, and 7 days of logs by default |
See How Geass works.
Are my databases backed up?
Section titled “Are my databases backed up?”Only if you turn backups on, and only for PostgreSQL, MySQL and SQLite databases that run in the cluster. They go to a bucket in your AWS account: Postgres continuously, so you can restore it to any recent moment, MySQL and SQLite daily. Redis and external databases have no backups in Geass. See Backups and restore.
Is Geass itself backed up?
Section titled “Is Geass itself backed up?”No. Geass makes no backup of the cluster’s own state. K3s’s embedded etcd takes its default snapshots (twice a day, five kept) in its data directory on the same disk, so they do not survive losing that disk, and Geass has no restore workflow for them. Keep your own record of your setup.
Can I restore my backups on a new cluster?
Section titled “Can I restore my backups on a new cluster?”Not from the dashboard. A restore starts from a backup record that lives in the cluster that made the backup. The objects stay in your S3 bucket, but a new cluster has no record of them. Dump the databases you cannot lose with their own tools before you retire a cluster. See Upgrade Geass.
What happens to my data when I uninstall?
Section titled “What happens to my data when I uninstall?”Uninstalling K3s deletes the cluster’s database and its local volumes. Longhorn’s replica data stays on disk, unreferenced. Things outside the cluster stay: S3 buckets and backups, DNS records, the Cloudflare tunnel, the GitHub App. Geass removes a bucket’s S3 bucket and IAM user only when you delete the bucket in the dashboard first. See Uninstall Geass.
Security and access
Section titled “Security and access”Who can sign in, and can I use single sign-on?
Section titled “Who can sign in, and can I use single sign-on?”Users come from a Kubernetes Secret, and each is an admin or a viewer. There is no single sign-on and no per-project permission. Scripts, the command line and agents use API tokens: Full access, Read only, with logs (the observer role), Read only, or a project token scoped to one environment of one project. See Users and API tokens.
Are my secrets safe?
Section titled “Are my secrets safe?”Secret variables are stored as Kubernetes Secrets and are never shown in the dashboard after you save them, and viewers do not see variable values at all. A Read only, with logs token sees the names of secrets and the values of plain variables, and every log line, so keep anything sensitive in a secret and do not print it. Dashboard passwords are stored as bcrypt hashes, and repeated failed sign-ins lock a user for a minute. Geass does not turn on K3s’s secrets encryption at rest, so the contents of Secrets are readable to anyone who can read the cluster’s database or its Secrets. Limit who has access to the control plane. See Security.
Can one project reach another?
Section titled “Can one project reach another?”Not by default. Each project environment is isolated by network policies, so only services of the same project, Geass itself and visitors through your domains reach its services. You allow other projects under Settings → Network of the receiving project. See Network isolation.
Scaling and placement
Section titled “Scaling and placement”Can I scale to zero?
Section titled “Can I scale to zero?”Yes, as Sleep when idle, for any service: an image, a build from GitHub, or a function. After a set time without requests (30 seconds to 24 hours; the dashboard takes minutes) Geass stops the service, and the next request to its public host starts it again, which waits a few seconds. It is opt-in. The installer does not install what it needs, KEDA and its HTTP add-on, so you turn on the serverless add-on once for the cluster (spec.addons.serverless.enabled). The service also needs a public host, because a request to it is what wakes it, and it cannot use CPU autoscaling. Calls from another service to its private address do not wake it. Databases and buckets do not sleep. See Sleep when idle.
Can I keep a project on certain servers for compliance?
Section titled “Can I keep a project on certain servers for compliance?”Yes, with compliance tags. Tag the nodes that qualify, for example hipaa, and mark the tag as a compliance tag on them (Usage, then Edit on a node). Then require it under the project’s Settings → Compliance. Everything the project runs, including its databases, buckets, builds and backup jobs, stays on nodes with the tag, those nodes take no other project’s work, and the project’s log history is not sent to the shared log store. It is about where Geass places work. It does not move data that is already elsewhere (a project with databases has to restore them into new ones first), it does not protect against a compromised node, and the control plane, backups to S3 and external databases sit outside it. See Compliance node tags.
Can I run code on a schedule?
Section titled “Can I run code on a schedule?”Yes, with a function. A function can have up to 8 schedules, each a cron expression in UTC that calls it with an HTTP POST, and a function can be an event handler that Geass serves HTTP for. Schedules start with the next deploy. See Functions and Command line. There is no schedule for other kinds of service.
Operating
Section titled “Operating”Where are the logs?
Section titled “Where are the logs?”In the dashboard, under each project’s Logs tab, and in a service’s Deployments tab (View logs). From a terminal, geass logs web -f follows a service’s logs; it needs an admin or a Read only, with logs token. The operator’s own log is sudo k3s kubectl -n geass-system logs deploy/geass-controller-manager -c manager. The installer’s log is a geass-install-*.log file. See Observability.
Where is the kubeconfig?
Section titled “Where is the kubeconfig?”/etc/rancher/k3s/k3s.yaml on the control plane, readable by root. sudo k3s kubectl uses it.
Something is not working.
Section titled “Something is not working.”Start with Troubleshooting. The getting-started pages each end with the failures that setup step is known for: Install Geass, Sign in to the dashboard, Add servers and Deploy your first app.