mait.sh1.69.2

Private beta: features and content may change. No warranty; use at your own risk.

Docs / Launcher and command-line tools

AIDE

Run local Kubernetes application infrastructure with project DNS, HTTPS ingress and routes to development processes.

For application developers using a Linux host who need realistic local service integration.

Read from the top for the basics; the later sections go deeper.

Beta
All components

What it doesBasics

  • Managed k3d lifecycle
  • Linux host DNS and development-certificate trust setup
  • Traefik ingress
  • Optional cluster-local service bridge
  • HMR routing between Services and local processes

First useBasics

  1. In a prepared Linux environment, deploy one application and verify its actual HTTPS response.
  2. Deploy the application stack.
  3. Route one Service to a local process, then restore it to pods.

Everyday tasksEveryday use

Provision a project’s first local cluster

A team needs local services behind DNS, TLS, and ingress without manually assembling the supporting infrastructure.

  1. On a supported Linux host, run AIDE setup --check before mutation; install with AIDC install AIDE, then run AIDE setup and review its sudo changes.
  2. Run AIDE login, then AIDE init with a unique project name and domain and an explicit development-CA choice; review the resulting .aide.yaml.
  3. Create the cluster and wait for its managed infrastructure and trust setup to converge.
  4. Inspect AIDE cluster status, deploy a small routed service, verify its HTTPS hostname, and delete the pilot cluster if the checkpoint fails.

What you getThe project has an addressable local Kubernetes environment with managed ingress, DNS, and development certificate trust.

How to check: Setup check passes; cluster status reports running infrastructure, working DNS, and trusted CA; the routed service responds through its expected HTTPS hostname.

Use local HMR through real ingress and backends

A frontend should reload from a local development server while retaining its normal hostname, TLS termination, ingress, and access to in-cluster services.

  1. Enable the cluster-local service bridge when the local process must reach backend Service FQDNs.
  2. Start the development server on a network-reachable address and confirm its port is listening.
  3. Switch the frontend Service to the external process while leaving its ingress definition unchanged.
  4. Verify the browser path and backend calls, then restore internal Service routing when the session ends.

What you getBrowser traffic reaches the live-reload process through the project’s normal ingress while the process can call real cluster backends by full Service FQDN.

How to check: Route status identifies the external endpoint; HTTPS uses the project hostname and certificate; backend calls reach the intended Services; set-internal or reset restores pod routing.

Settings to decideAdvanced

Choose a unique project name and domain
Treat both values as durable cluster identity. Use a domain that will not overlap another active local cluster and that is appropriate for development-only trust.
Choose generated or supplied CA material
Use either a generated development CA or an explicit certificate-and-key pair, never both. Keep development trust separate from production certificate authorities. For a retained environment, verify the effective issuer and browser trust after a restart.
Declare storage and exposed ports
Use named volumes for runtime-managed persistence or reviewed bind mounts for host-owned data. A non-empty port list replaces the defaults, so retain 80 and 443 when ingress needs them.
Opt into cluster-Service bridging only when needed
Enable the service bridge for local processes that must reach full .svc.cluster.local names. Pin the Docker subnet when NetworkPolicy must admit a stable source range.

CommandsAdvanced

$ aidc install aide
$ aide setup --check
$ aide setup
$ aide login --code <activation-code>
$ aide init --name <project> --domain <domain> --ca-generate
$ aide cluster create
$ aide cluster status
$ aide route set-external <service> --port <port>
$ aide route set-internal <service>

Problems and fixesHelp

What you seeCheckFix
Cluster creation stops before provisioning because a tool, helper, credential, disk, or Docker prerequisite is missing.Run AIDE setup --check and AIDE doctor, then read the specific preflight failure instead of partially provisioning by hand.Install or authorize the named prerequisite, free required disk space, and rerun create only after the checks pass.
The project hostname does not resolve or the browser rejects its development certificate.Use cluster status to distinguish DNS forwarding from CA trust, then confirm dnsmasq, ingress hostname annotations, and the browser’s certificate store.Repair AIDE setup and follow the documented retained-cluster recovery path. After restart, verify the effective certificate issuer and browser trust as well as DNS before changing application resources.
A route switch refuses the local target or the routed page does not respond.Confirm the process listens beyond loopback, the selected port is reachable from the workspace network, and route status names the expected endpoint.Bind the process to a reachable address, retry the guarded route switch, and use route reset if prior routing state is unclear.
A full cluster Service FQDN resolves from the workspace but the connection is refused or times out.Confirm DNS resolution and the Service CIDR route, then inspect application NetworkPolicy for the workspace address.Add a deliberate, scoped ipBlock rule for the workspace address and required port when policy permits.
What you see
Cluster creation stops before provisioning because a tool, helper, credential, disk, or Docker prerequisite is missing.
Check
Run AIDE setup --check and AIDE doctor, then read the specific preflight failure instead of partially provisioning by hand.
Fix
Install or authorize the named prerequisite, free required disk space, and rerun create only after the checks pass.
What you see
The project hostname does not resolve or the browser rejects its development certificate.
Check
Use cluster status to distinguish DNS forwarding from CA trust, then confirm dnsmasq, ingress hostname annotations, and the browser’s certificate store.
Fix
Repair AIDE setup and follow the documented retained-cluster recovery path. After restart, verify the effective certificate issuer and browser trust as well as DNS before changing application resources.
What you see
A route switch refuses the local target or the routed page does not respond.
Check
Confirm the process listens beyond loopback, the selected port is reachable from the workspace network, and route status names the expected endpoint.
Fix
Bind the process to a reachable address, retry the guarded route switch, and use route reset if prior routing state is unclear.
What you see
A full cluster Service FQDN resolves from the workspace but the connection is refused or times out.
Check
Confirm DNS resolution and the Service CIDR route, then inspect application NetworkPolicy for the workspace address.
Fix
Add a deliberate, scoped ipBlock rule for the workspace address and required port when policy permits.

All AIDE problems and fixes →

Good to knowHelp

  • AIDE local-cluster host integration, including its privileged host setup, runs on Linux hosts.
  • AIDE prepares local application infrastructure; the developer or agent deploys the application and verifies its response.