satusky.toml Reference

satusky.toml is the project-level configuration file for a Satusky deployment. It captures the shape of your app — resource requirements, port, Dockerfile path — so you can run 1ctl deploy without repeating flags on every invocation.

Running 1ctl init generates a starter satusky.toml in the current directory. The file contains no secrets and no credentials; it is safe to commit to source control.

---

File resolution

1ctl resolves the config file in this order:

Invocation	File resolved
1ctl deploy	./satusky.toml in the current directory
1ctl deploy --config staging	./satusky.staging.toml
1ctl deploy --config production	./satusky.production.toml
1ctl deploy --config ./infra/satusky.toml	Exact path provided

When --config receives a bare name (no path separators, no .toml extension), 1ctl expands it to satusky.<name>.toml in the current directory. When it receives a path (contains / or ends in .toml), it is used verbatim.

---

Priority

When the same setting is expressible both in satusky.toml and as a CLI flag, the following precedence applies:

CLI flags  >  satusky.toml  >  platform defaults

For example, 1ctl deploy --cpu 2 overrides cpu = "0.5" in satusky.toml for that single invocation without modifying the file.

---

Field reference

[app]

The [app] section defines the workload identity, container port, build file, and default compute shape.

Field	Type	Default	Description
name	string	required	App identifier. Used as the Kubernetes app label. Must be unique within your organization. Lowercase letters, digits, and hyphens only — no spaces.
port	integer	8080	Port your container listens on. Satusky routes all HTTP ingress traffic to this port.
cpu	string	"0.5"	CPU allocation. Accepts float ("0.5", "1"), integer ("1"), or millicores ("500m"). See CPU & Memory Formats.
memory	string	"256Mi"	Memory allocation. Kubernetes binary notation: "128Mi", "256Mi", "512Mi", "1Gi", "2Gi", "4Gi". See CPU & Memory Formats.
dockerfile	string	"Dockerfile"	Path to the Dockerfile, relative to the project root.
replicas	integer	1	Initial replica count. Overridden at runtime by HPA when autoscaling is enabled.

[volume]

The [volume] section requests a persistent volume for data that must survive pod replacement.

Field	Type	Default	Description
size	string	unset	Persistent volume size, e.g. "1Gi", "10Gi". Equivalent to 1ctl deploy --volume-size.
mount	string	unset	Container path where the volume is mounted, e.g. "/app/data". Equivalent to 1ctl deploy --volume-mount.

Both fields are required if the section is present.

[volume]
size = "1Gi"
mount = "/app/data"

Implemented. 1ctl deploy reads this section and creates a PVC/mount through the same path as the volume flags.

Known gap. Full volume lifecycle management is not yet a complete CLI contract. Verify PVC creation and deletion explicitly until 1ctl exposes first-class volume commands.

Advanced sections

The current parser also accepts structured sections for autoscaling, disruption budgets, and multi-cluster deployment. These map to the corresponding 1ctl deploy flags:

Section	Purpose
[hpa]	Horizontal Pod Autoscaler configuration.
[vpa]	Vertical Pod Autoscaler configuration.
[pdb]	PodDisruptionBudget configuration.
[multicluster]	Multi-cluster deployment and backup policy.

Use 1ctl init and 1ctl deploy --help as the source of truth for supported fields while these sections evolve.

---

Example files

Minimal

The smallest valid satusky.toml:

[app]
name   = "my-api"
port   = 8080
cpu    = "0.5"
memory = "256Mi"

Frontend (nginx on port 80)

[app]
name       = "frontend"
port       = 80
cpu        = "0.25"
memory     = "128Mi"
dockerfile = "Dockerfile"

Production with multiple replicas

[app]
name     = "api-prod"
port     = 8080
cpu      = "1"
memory   = "512Mi"
replicas = 3

Stateful app with persistent data

[app]
name       = "diagnosis-bot"
port       = 8080
cpu        = "1"
memory     = "256Mi"
dockerfile = "Dockerfile"

[volume]
size  = "1Gi"
mount = "/app/data"

For this example, the application stores SQLite files under /app/data. Without the [volume] section, those files live in the container writable layer and are not durable across pod replacement.

---

Multiple environments

The recommended pattern is one config file per environment, all committed to source control:

File	Deployed with
satusky.toml	1ctl deploy (default)
satusky.staging.toml	1ctl deploy --config staging
satusky.production.toml	1ctl deploy --config production

Because satusky.toml contains no secrets — only resource shape and app name — committing all environment configs is safe. Secrets are managed separately via 1ctl secret create and 1ctl env create.

A typical project layout:

my-api/
├── satusky.toml              # dev / default
├── satusky.staging.toml      # staging environment
├── satusky.production.toml   # production environment
├── Dockerfile
└── src/

---

What satusky.toml does NOT contain

The following are intentionally outside the scope of satusky.toml:

Concern	Where it lives
Secrets and sensitive environment variables	1ctl secret create
Non-sensitive environment variables	1ctl env create or repeatable --env flags
API tokens and org IDs	~/.satusky/context.json (set by 1ctl auth login)
Custom domain configuration	--domain flag on 1ctl deploy, or 1ctl domains add
Ingress and TLS settings	Managed automatically by the platform

Keeping satusky.toml free of sensitive data is a deliberate design constraint so the file can be committed safely.

---

Runtime resolution

When 1ctl deploy runs:

1. The CLI reads name from satusky.toml.
2. It resolves the current organization’s namespace from ~/.satusky/context.json.
3. It calls GET /v1/cli/deployments/namespace/{namespace} to find any existing deployment with a matching app label.
4. It submits POST /v1/cli/deployments/upsert/{namespace}/{appLabel} with the merged spec.

Changing name creates a new deployment. It does not rename the existing one. The old deployment continues running under the old name until you destroy it explicitly with 1ctl deploy destroy.

The upsert is idempotent. Running 1ctl deploy multiple times with the same name updates the existing deployment in-place. This makes it safe to run from CI on every push.