Search for a command to run...
How an AI-native investigation runtime recreates infrastructure failures in isolated AWS-compatible sandboxes, retains the evidence, and verifies the repair.
No comments yet. Be the first to comment.
The hardest cloud incident is often the one that cannot be reproduced safely.
Production is too risky for experiments. Staging has drifted. Logs are incomplete. By the time another engineer joins, the environment that produced the failure has changed.
Gigan treats this as a runtime architecture problem, not a prompt-writing problem.
It turns a problem statement or Terraform project into an isolated AWS-compatible environment. Agents can inspect, change, validate, pause, and replay that environment without touching production AWS.
The result is not merely a chat response. It is a bounded investigation whose claims remain connected to commands, resource state, tool output, and explicit validation.
Gigan is composed of six cooperating systems:
a planner that converts intent into a typed resource graph,
a Strands runtime that coordinates planners, specialists, tools, and judges,
a policy layer that resolves every action against the current session,
a control plane that owns privileged Docker operations,
a Floci sandbox that supplies disposable AWS-compatible infrastructure,
a durable evidence store that outlives any model call or container.
These systems form an authority chain. The model proposes intent. Gigan validates and translates it. The control plane manages containers. Floci executes cloud operations. PostgreSQL records what actually happened.
The web workspace is a view over this system. It does not own infrastructure state, sandbox addresses, model memory, or Docker authority.
That division matters because an infrastructure agent should never be able to turn a plausible sentence into unreviewed host access.
Floci provides the AWS-compatible API surface inside each active Gigan session. Gigan wraps that emulator with lifecycle management, resource planning, backing containers, evidence capture, and replay.
Every active session receives a runtime ID, a managed container name, an endpoint, a Docker network assignment, and a resource graph.
The endpoint is resolved from current runtime state. It is not copied from model memory or trusted after a backend restart.
When provisioning starts, Gigan asks its internal control plane to create a named Floci runtime. The runtime is labelled with its Gigan ownership and runtime ID.
Those labels let the control plane reconcile assignments from Docker after the control-plane process restarts. Recovery is based on managed runtime metadata, not an in-memory dictionary alone.
The backend reaches Floci through container DNS on port 4566. AWS CLI commands are sent to that assigned endpoint, so one session cannot accidentally operate on another session's emulator.
Some emulated resources need more than API records. EC2, RDS, and EKS scenarios can create backing containers that support Linux commands, service processes, or Kubernetes operations.
Gigan allocates runtime-specific host-port shards for EC2 SSH, application ports, and EKS API servers. This reduces collisions when several investigations run on one Docker host.
Floci and its child containers share a sandbox network. The backend can also attach through its application network for health checks and controlled command execution.
Only the Gigan control-plane service mounts the Docker socket. Its command validator allows a small set of operations against Gigan-managed names.
The agent never receives the socket. The browser never calls the control plane. A sandbox cannot request arbitrary Docker operations against unrelated containers.
Pausing a session asks this control plane to remove the runtime and its managed children. The expensive, mutable layer disappears while the investigation record remains.
Floci is still an emulator. Its service coverage and behavior define the limit of the experiment. A sandbox result is evidence about the reproduced system, not proof of every production AWS edge case.
The language model is not Gigan's infrastructure executor. It is one input to a constrained compilation pipeline.
The pipeline turns uncertain language into deterministic operations through six stages.
The infrastructure planner returns structured output rather than free-form shell commands.
Each proposed resource has a logical key, a supported type, configuration, and dependency keys. The plan can also carry investigation notes and scenario-specific follow-up prompts.
Known scenarios have deterministic plans. When a live model is unavailable or structured planning fails, Gigan can fall back to its supported plan catalog instead of inventing malformed commands.
The proposed graph is filtered through a provisionable resource allowlist. Unsupported resource types cannot pass directly to execution.
Gigan then applies topology rules. It can enforce requested cardinality, connect ALB components, complete EKS network dependencies, and reject missing logical references.
Network repair is deterministic. Invalid, overlapping, or out-of-parent CIDRs are replaced with valid non-overlapping ranges before provisioning begins.
A fault-note is intentionally different from a cloud resource. It records the degraded condition the scenario is meant to investigate without pretending that an AWS object was created.
The planner's logical dependencies become a directed acyclic graph.
A subnet depends on a VPC. An instance may depend on a subnet and security group. A listener depends on a load balancer and target group.
Logical keys remain stable during planning, while actual provider IDs are resolved only after creation.
Gigan groups nodes whose dependencies are already satisfied. Independent resources in one wave are created concurrently with asyncio.gather.
The next wave starts only after upstream IDs are available. This gives the system parallelism without ignoring cloud dependency order.
The backend, not the model, owns the AWS CLI templates for supported resources.
When Floci returns a VPC ID, Gigan stores it under the VPC's logical key. Downstream subnet, route, security-group, and instance commands receive that actual ID.
Command output and configuration failures determine whether each materialized node is created, degraded, or error.
The completed graph becomes shared state for the topology canvas, resource operations, agent tools, pause and resume, replay, and investigation history.
The graph is therefore more than a diagram. It is the runtime address book and dependency model used by every later action.
Gigan uses one application adapter around native Strands Agents, but it creates a fresh Strands runtime for each invocation.
Cross-request state is restored from PostgreSQL. A long-lived model object is never the hidden owner of conversation, resources, evidence, or memory.
The adapter exposes several orchestration modes because planning, analysis, operation, and verification are different workloads.
| Workload | Strands mode | Responsibility |
|---|---|---|
| Infrastructure planning | Schema-constrained completion | Produce a typed resource plan |
| Terraform recovery | Parser sub-agent | Recover supported resources from ambiguous HCL |
| Parallel analysis | GraphBuilder specialists plus synthesis |
Analyze independent scopes concurrently |
| Interactive operation | Tool-using agent with GoalLoop |
Gather evidence and perform bounded changes |
| Verification | Separate judge configuration | Check the goal against retained evidence |
| Final response | Tool-free synthesis | Explain verified results and remaining blockers |
Planning calls use Pydantic result contracts. If the provider does not return the expected schema, Gigan treats that as a failed planning path rather than executing prose.
The same mechanism creates sequential plans and partitions parallel work into bounded task lists.
For parallel analysis, a planner first produces independent scopes. Gigan caps the number of scopes and creates one specialist node per scope.
Each specialist receives a focused system prompt and works only on its assigned problem. Directed edges connect every specialist to one synthesis node.
The graph defines node timeouts, total execution timeout, and a maximum execution count. A partial or failed graph cannot be reported as a completed synthesis.
This is different from asking one model to imitate several roles in one response. Strands schedules separate nodes and returns accumulated usage, metrics, status, and execution timing.
Interactive work uses Strands GoalLoop. The maker chooses evidence-gathering actions or a bounded repair. A separate judge checks whether the requested outcome is supported.
The loop preserves context across attempts but has explicit attempt and time budgets. Tool-round and total execution limits add further bounds.
Failed checks return feedback into the next attempt. The loop ends with a verified goal, exhausted budget, timeout, or unresolved blocker.
After tool use and judging, a tool-free synthesis step explains the outcome.
It receives the pass state, stop reason, attempts, and retained evidence. It cannot run another hidden mutation or convert an unverified action into success.
This separation keeps explanation downstream of execution and verification.
Agents operate through application-owned tools such as inspect_session_state, run_aws_cli, run_ec2_shell, and run_kubectl.
Each invocation receives current session state from the application. The tool resolves targets against the materialized resource graph instead of trusting IDs remembered by the model.
run_aws_cli applies command policy and injects the selected Floci endpoint. The model does not choose --endpoint-url or an arbitrary host.
run_ec2_shell requires a concrete instance when several EC2 resources exist. Gigan maps that instance to its backing container before running the bounded Linux command.
run_kubectl targets the session's recreated Kubernetes environment and applies command policy around cluster mutations and verification.
Every result carries the command, output, exit code, source, resource association, and timestamp. Tool output is investigation evidence, not temporary prompt text.
One interactive turn follows a strict sequence:
restore the session graph, conversation, investigation, and relevant memories,
inspect current state through scoped tools,
choose one evidence-gathering action or bounded mutation,
execute through the policy and runtime boundaries,
persist the exact result,
judge the goal against retained evidence,
synthesize a user-facing answer from the verified state.
Inspection goals require concrete observations. Mutation goals require evidence of both the change and a later verification.
An exit code of zero is not enough. A successful create command does not prove connectivity, target health, workload readiness, or policy behavior.
The checker can request another materially different attempt. It cannot run forever, and it cannot erase a failed command from the record.
Lifecycle hooks capture model calls, graph nodes, tool execution, errors, timing, and token usage. AgentOps can receive those traces while prompt and tool content remain redacted by default.
A disposable runtime should not make the investigation disposable.
PostgreSQL stores four distinct kinds of truth:
the materialized session and investigation state,
append-only lifecycle, chat, command, resource, and investigation events,
the latest resource inventory and dependency metadata,
semantic, episodic, and procedural agent memories.
This means a browser refresh, backend restart, or model-provider change does not erase the investigation.
Pausing removes the Floci runtime and backing containers. The session becomes read-only, but its graph, evidence, messages, memories, snapshots, and validation history remain available.
Resuming does not trust the old endpoint. Gigan starts a fresh runtime and replays the supported saved resource plan.
New provider IDs are captured and remapped into the recreated dependency graph. Commands unlock only after provisioning reaches a usable state.
Snapshots provide comparison points across the investigation. Replay can show how resources, status, and evidence changed between the original state, a repair, and a recreated runtime.
Validation stores explicit checks and confidence history. Together, replay and validation make the work reviewable after the original containers no longer exist.
Terraform is another source of resource intent, not a separate execution system.
Gigan accepts a folder, ZIP archive, or supported GitHub repository. Its deterministic parser extracts known AWS blocks and logical references.
Ambiguous HCL can be passed to a schema-constrained parser sub-agent when a live model is configured.
The recovered resources then enter the same allowlist, dependency normalization, topology repair, provisioning, evidence, and persistence pipeline used by natural-language scenarios.
After investigation, Gigan can export the supported materialized state as modular Terraform grouped by network, compute, storage, messaging, and IAM concerns.
The round trip is deliberate:
import or describe infrastructure,
normalize it into a supported graph,
reproduce the failure in Floci,
gather runtime evidence,
apply a bounded repair,
verify the outcome,
export infrastructure and investigation artifacts.
The interface is useful because it exposes the same state used by the agents and runtime, not because it duplicates cloud-console pages.
The topology is the materialized resource graph. Selecting a node scopes inspection and operations to that resource. Console entries are retained tool events, not a separate terminal transcript.
Investigation keeps observations, hypotheses, and proposed changes distinct. An engineer can inspect the evidence behind a claim before accepting a mutation or validation result.
Gigan is an investigation runtime for emulated AWS-compatible infrastructure.
It is useful for reproducing network, policy, compute, database, load-balancing, Terraform, and Kubernetes scenarios without exposing a production cloud account.
It is not a replacement for production telemetry, provider documentation, change management, human approval, or final testing against AWS.
Unsupported resources and emulator gaps must remain visible. The system is designed to report a blocker rather than invent provider behavior that did not occur.
Local model quality also matters. Planning and tool use require reliable structured output, adequate context, and tool-calling support.
The strongest guarantee is narrow and practical: inside the reproduced sandbox, a claim should be backed by inspectable runtime evidence.
Gigan is open source under the MIT license.
Docker Compose and a Gemini API key provide the default setup. LM Studio, Unsloth Studio, and other OpenAI-compatible endpoints are explicit opt-in providers.
git clone https://github.com/Faizullah9181/Gigan.git
cd Gigan
cp backend/.env.example backend/.env
cp frontend/.env.example frontend/.env
Add the Gemini key to backend/.env:
GEMINI_API_KEY=your-gemini-api-key
Start the stack:
docker compose up --build
The application runs at http://localhost:5173. The API runs at http://localhost:8000, with OpenAPI documentation at http://localhost:8000/docs.
Without a live model, deterministic scenario planning remains available. Model-backed planning, parser recovery, and agent conversations are limited.
The important architectural decision in Gigan is that no single agent owns the whole system.
Planners produce typed intent. Specialist graphs analyze bounded scopes. Tool agents operate through policy. Judges verify evidence. The control plane owns containers. Floci owns disposable cloud state.
PostgreSQL owns durable truth.
That division turns an infrastructure conversation into a reproducible investigation whose commands, state transitions, failures, repairs, and remaining blockers can be inspected later.