Skip to content

Why It Exists

Coding agents can produce internal apps faster than most teams can safely deploy them.

Without a shared platform, each app tends to grow its own deployment script, fixed port, environment variable pattern, auth behavior, and README. That works for one app. It becomes fragile at ten apps and risky at fifty.

InHouseCloud creates a small cloud control plane around one machine:

  • a standard ingress route;
  • a default auth layer;
  • local Git as the source of truth;
  • shared runtime services;
  • host and container visibility;
  • a manifest for intent;
  • a template for repeatability;
  • checks for confidence;
  • push to main for approval;
  • an executor in the deploy job for runtime state;
  • a portal for visibility;
  • rules that agents can follow without needing production access.

What makes this different

This project is intentionally smaller than a full platform-as-a-service and stricter than a pile of scripts.

  • It keeps the app contract in Git, close to the code.
  • It lets companies run on simple infrastructure first.
  • It treats AI agents as contributors that need rules, feedback, and boundaries.
  • It separates validation from deployment.
  • It keeps production credentials on the box (the install .env and each app's env file), not in chat, manifests, or app repos.
  • It makes health and deploy state visible to humans and agents.

Advantages

For small teams

  • Start with one host and Docker Compose instead of a full Kubernetes platform.
  • Get a repeatable path for internal apps without building a large platform team.
  • Keep operational decisions visible in Git.

For platform teams

  • Standardize app metadata, ownership, auth, health, and deploy behavior.
  • Make drift visible by comparing Git intent with runtime reality.
  • Introduce stronger backends later without changing the app contract.

For coding agents

  • Give agents a clear contract instead of tribal knowledge.
  • Let agents fix validation failures from actionable feedback.
  • Avoid giving agents broad production access.
  • Make generated apps easier to review because they follow the same shape.

For security and operations

  • Pull requests run checks on the CI runner, without the Docker socket or deploy credentials.
  • New apps require auth by default.
  • Port allocation can be centralized.
  • Secrets stay out of manifests and .env.example.
  • Destructive actions are outside the default automation path.

Safety principles

  • Git is the source of truth for app intent.
  • Pull requests validate without production secrets.
  • Real deployment happens only on a push to main, the explicit approval signal.
  • App manifests never contain secret values.
  • New apps use automatic port allocation by default.
  • Internal apps should require authentication by default.
  • The cloud never deletes databases, volumes, repositories, stacks, or proxy routes automatically.
  • Runtime changes should be previewable before they are applied.
  • Agent-facing errors should explain the next fix, not just the failed check.

How they are enforced, and the trust boundary of each piece: security.md.

Lessons behind the architecture

This project grew from a practical pattern: agent-built apps become useful quickly, but they need a boring operational path to stay safe.

The key lessons:

  • A template is not enough. Teams need a contract, checks, and a deploy path.
  • A manifest beats scattered README instructions because it can be validated.
  • The approval belongs where review already happens: the app's own main.
  • Agents should prepare and repair deployment artifacts; the deploy itself is a script anyone can read, not an agent improvising on the box.
  • Health checks need to be part of the contract, not an afterthought.
  • Auth should be the default for internal apps, with explicit exceptions.
  • Automatic port allocation prevents slow, hidden conflicts.
  • The portal should observe and compare state; Git should remain the source of app intent.
  • The simplest workable runtime is often the right starting point, as long as the contract can outlive it.

What the first real box taught the install design: install-design.md.