├── .devin
└── wiki.json
├── .dockerignore
├── .gitignore
├── CONTRIBUTING.md
├── LICENSE
├── MANIFEST.in
├── Makefile
├── README.md
├── ROADMAP.md
├── SECURITY.md
├── assets
├── demo-k7.gif
├── k7-console-dev.png
├── k7-cover-upgrade.png
└── show-hn_nb1_post-id-45656952.png
├── debian
├── changelog
├── clean
├── control
├── copyright
├── k7.install
├── rules
└── source
│ ├── format
│ └── options
├── docs
├── README.md
├── ai-tools
│ ├── claude-code.mdx
│ ├── cursor.mdx
│ └── windsurf.mdx
├── api
│ ├── endpoints
│ │ ├── exec.mdx
│ │ ├── health.mdx
│ │ ├── metrics.mdx
│ │ └── sandboxes.mdx
│ ├── introduction.mdx
│ └── security.mdx
├── development.mdx
├── docs.json
├── essentials
│ ├── code.mdx
│ ├── images.mdx
│ ├── markdown.mdx
│ ├── navigation.mdx
│ ├── reusable-snippets.mdx
│ └── settings.mdx
├── favicon.png
├── getting-started
│ └── installation.mdx
├── guides
│ ├── cli.mdx
│ ├── langchain-agent.mdx
│ ├── python-sdk.mdx
│ ├── releasing.mdx
│ └── utilities.mdx
├── images
│ ├── ex-api-status.png
│ ├── ex-create.png
│ ├── ex-generate-api-key.png
│ ├── ex-get-api-endpoint.png
│ ├── ex-install.png
│ ├── ex-list-api-keys.png
│ ├── ex-list.png
│ ├── ex-revoke-api-key.png
│ ├── ex-shell.png
│ ├── ex-start-api.png
│ ├── ex-stop-api.png
│ ├── ex-top.png
│ ├── k7-cover-upgrade.png
│ └── k7-logo.png
├── index.mdx
├── snippets
│ └── snippet-intro.mdx
└── tutorials
│ └── k7_hetzner_node_setup.pdf
├── examples
└── k7.yaml
├── setup.py
├── src
├── README.md
├── k7
│ ├── README.md
│ ├── __init__.py
│ ├── api
│ │ ├── Dockerfile.api
│ │ ├── __init__.py
│ │ ├── docker-compose.yml
│ │ ├── main.py
│ │ └── requirements.txt
│ ├── cli
│ │ ├── Dockerfile.cli
│ │ ├── build.sh
│ │ ├── install.sh
│ │ └── k7.py
│ ├── core
│ │ ├── __init__.py
│ │ ├── core.py
│ │ └── models.py
│ └── deploy
│ │ ├── inventory.local.ini
│ │ └── k7-install-node.yaml
└── katakate
│ ├── __init__.py
│ └── client.py
├── tutorials
├── k7_hetzner_node_setup.pdf
└── langchain-react-agent
│ ├── .env.example
│ ├── README.md
│ ├── agent.py
│ └── requirements.txt
└── utils
├── README.md
├── stress_test.sh
└── wipe-disk.sh
/.devin/wiki.json:
--------------------------------------------------------------------------------
1 | {
2 | "repo_notes": [
3 | {
4 | "content": "Start the wiki with an Architecture section that opens with diagrams explaining how Kubernetes (single-node K3s), Kata, and Firecracker fit together. Do NOT show multiple nodes yet — only a single K3s node is supported currently.",
5 | "author": "Editors"
6 | },
7 | {
8 | "content": "Katakate (k7) provides self-hosted secure VM sandboxes on Kubernetes using Kata + Firecracker. Code lives under src/k7 (CLI, API, core) and src/katakate (Python SDK). Use this as the source of truth for deep architecture and behavior; the Mintlify docs under docs/ are user-facing.",
9 | "author": "Maintainers"
10 | },
11 | {
12 | "content": "Security is central: VM isolation via Kata/Firecracker + Jailer, default capability drop, non-root options, Seccomp RuntimeDefault, deny-all ingress, optional egress whitelist with DNS allowance. Keep this model explicit and front-and-center.",
13 | "author": "Maintainers"
14 | },
15 | {
16 | "content": "Core flows to document deeply: sandbox lifecycle (create/list/delete), before_script execution and readiness probe, egress lockdown policy generation, metrics fetching via metrics.k8s.io. Implemented in src/k7/core/core.py.",
17 | "author": "Maintainers"
18 | },
19 | {
20 | "content": "API key management (generation, storage, expiry, last_used) lives in src/k7/api/main.py and CLI commands. Keys are stored at /etc/k7/api_keys.json (0600).",
21 | "author": "Maintainers"
22 | },
23 | {
24 | "content": "The API is deployed with Docker Compose using embedded compose/Dockerfile resolved at runtime by K7Core._get_embedded_docker_compose(). Explain kubeconfig override behavior and Cloudflared tunnel URL discovery.",
25 | "author": "Maintainers"
26 | },
27 | {
28 | "content": "Packaging: PyPI ships only src/katakate; CLI/API are packaged as .deb under dist/ via src/k7/cli/build.sh. Do not conflate these paths in installation instructions.",
29 | "author": "Maintainers"
30 | },
31 | {
32 | "content": "Examples and templates live in examples/ (sandbox YAMLs) and tutorials/ (LangChain agent). Reuse when explaining quickstarts.",
33 | "author": "Maintainers"
34 | },
35 | {
36 | "content": "Known issue: Jailer may be ignored by Kata despite configuration; see README Known issues. Mention as caveat.",
37 | "author": "Maintainers"
38 | }
39 | ],
40 | "pages": [
41 | {
42 | "title": "Architecture",
43 | "purpose": "Kubernetes + K3s, Kata, Firecracker, Devmapper thin-pool; how components interact (diagrams first)",
44 | "parent": null,
45 | "page_notes": [
46 | {
47 | "content": "Begin the page with a large, single-node diagram: one K3s node on the host OS. Inside it, depict a Kubernetes Pod configured with runtimeClass 'kata' that launches a Kata microVM (Firecracker). Inside the microVM, show the kata-agent, the guest rootfs, and the container root filesystem. Clearly label boundaries: Host OS, Kubernetes, VM boundary (Firecracker), and Container."
48 | },
49 | {
50 | "content": "Show the storage path: container image layers resolved by containerd's devmapper snapshotter into a thin pool of logical volumes (LVs). Each sandbox gets an LV snapshot (thin-provisioned). Explain copy-on-write behavior at the disk block level (blocks are shared until written); memory is not shared across microVMs."
51 | },
52 | {
53 | "content": "Illustrate how the snapshot LV is attached to the Firecracker microVM as a block device and becomes the container rootfs inside the guest. Call out where 'before_script' writes go (into the snapshot)."
54 | },
55 | {
56 | "content": "Add a second, focused diagram for storage only: Image layers -> devmapper thin pool -> per-sandbox snapshot LV (CoW) -> Firecracker drive -> guest mount -> container rootfs."
57 | },
58 | {
59 | "content": "Important: depict only a single node (single K3s). Avoid multi-node cluster visuals for now. Optionally add a small 'Coming soon' note about multi-node."
60 | },
61 | {
62 | "content": "Make it clear the single node can run many sandbox pods concurrently (dozens per node) without drawing them all: add a small annotation/arrow like '... more kata pods' with a brief capacity note."
63 | }
64 | ]
65 | },
66 | {
67 | "title": "Katakate Overview",
68 | "purpose": "What K7 is, capabilities, core value, links to docs and repo structure",
69 | "parent": null
70 | },
71 | {
72 | "title": "Installation & Node Setup",
73 | "purpose": "Node requirements, APT install, Ansible-driven installer flow and progress events",
74 | "parent": null
75 | },
76 | {
77 | "title": "CLI Usage",
78 | "purpose": "How to manage sandboxes from nodes; commands: install, create, list, delete, delete-all, logs, shell, top",
79 | "parent": null,
80 | "page_notes": [
81 | { "content": "Reference src/k7/cli/k7.py for exact options and behaviors." }
82 | ]
83 | },
84 | {
85 | "title": "Sandbox Configuration (k7.yaml)",
86 | "purpose": "Explain YAML fields (name, image, namespace, limits, env_file, before_script, egress_whitelist, security flags cap_add/cap_drop, non-root)",
87 | "parent": "CLI Usage"
88 | },
89 | {
90 | "title": "API Overview",
91 | "purpose": "FastAPI service, auth via API keys, error schema, health",
92 | "parent": null,
93 | "page_notes": [
94 | { "content": "Entry point: src/k7/api/main.py; app title/version from k7.__version__." }
95 | ]
96 | },
97 | {
98 | "title": "Authentication & API Keys",
99 | "purpose": "Key creation/list/revoke, storage, expiry, last_used update, headers (X-API-Key or Bearer)",
100 | "parent": "API Overview"
101 | },
102 | {
103 | "title": "API Endpoints",
104 | "purpose": "REST endpoints for sandboxes, exec, metrics, health with request/response shapes",
105 | "parent": "API Overview"
106 | },
107 | {
108 | "title": "API: Sandboxes",
109 | "purpose": "POST /api/v1/sandboxes, GET list/get, DELETE single/all, Location header behavior",
110 | "parent": "API Endpoints"
111 | },
112 | {
113 | "title": "API: Exec",
114 | "purpose": "POST /api/v1/sandboxes/{name}/exec to run commands; response fields",
115 | "parent": "API Endpoints"
116 | },
117 | {
118 | "title": "API: Metrics",
119 | "purpose": "GET /api/v1/sandboxes/metrics; source: metrics.k8s.io; units parsing",
120 | "parent": "API Endpoints"
121 | },
122 | {
123 | "title": "API: Health",
124 | "purpose": "GET /health and root",
125 | "parent": "API Endpoints"
126 | },
127 | {
128 | "title": "Python SDK",
129 | "purpose": "Using katakate Client/AsyncClient to create/list/exec/delete sandboxes; install via pip",
130 | "parent": null,
131 | "page_notes": [
132 | { "content": "Point to src/katakate/client.py; mirror README examples and types." }
133 | ]
134 | },
135 | {
136 | "title": "Security Model",
137 | "purpose": "Explain VM isolation, seccomp, capabilities, non-root modes at pod/container level, network isolation strategy",
138 | "parent": null
139 | },
140 | {
141 | "title": "Network Policies",
142 | "purpose": "Egress whitelist generation + kube-dns allow; deny-all ingress policy created for sandbox label selector",
143 | "parent": "Security Model"
144 | },
145 | {
146 | "title": "Before Script Lifecycle",
147 | "purpose": "How before_script runs inside main container; readiness gating file; log streaming behavior in CLI",
148 | "parent": "Sandbox Configuration (k7.yaml)"
149 | },
150 | {
151 | "title": "Metrics and Monitoring",
152 | "purpose": "How top command parses CPU n/u/m units and memory Ki/Mi/Gi; limitations",
153 | "parent": null
154 | },
155 | {
156 | "title": "Packaging & Releases",
157 | "purpose": "Distribution strategy: PyPI for SDK, Debian for CLI/API; build and install flow",
158 | "parent": null
159 | },
160 | {
161 | "title": "Tutorials",
162 | "purpose": "Walk through LangChain ReAct agent with K7 sandbox tool",
163 | "parent": null
164 | },
165 | {
166 | "title": "Development",
167 | "purpose": "Build from source, API container build/run, repo layout, contribution pointers",
168 | "parent": null
169 | },
170 | {
171 | "title": "Known Issues & Caveats",
172 | "purpose": "Document current limitations (Jailer ignore), roadmap items",
173 | "parent": null
174 | }
175 | ]
176 | }
177 |
178 |
179 |
--------------------------------------------------------------------------------
/.dockerignore:
--------------------------------------------------------------------------------
1 | **/__pycache__/
2 | **/*.pyc
3 | **/*.pyo
4 | **/*.pyd
5 |
6 | /dist/
7 | !dist/*.deb
8 |
9 | .git
10 | .gitignore
11 | **/.DS_Store
12 | **/.vscode/
13 | **/.idea/
14 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Python
2 | __pycache__/
3 | *.py[cod]
4 | *.egg-info/
5 | .venv*/
6 | .env
7 |
8 | # Build artifacts
9 | dist/
10 | build/
11 | *.egg
12 | *.deb
13 |
14 | # Debian packaging artifacts
15 | *.buildinfo
16 | *.changes
17 | *.dsc
18 | *.tar.xz
19 | *.tar.gz
20 | *.build
21 | debian/.debhelper/
22 | debian/debhelper-build-stamp
23 | debian/files
24 | debian/k7.substvars
25 |
26 | # Nuitka artifacts
27 | *.onefile-build/
28 | .nuitka-cache/
29 |
30 | # Local tooling
31 | .pytest_cache/
32 | .mypy_cache/
33 | .ruff_cache/
34 | .coverage
35 | coverage.xml
36 |
37 | # IDE/editor
38 | .vscode/
39 | .idea/
40 |
41 | # Work directories (ignore any 'work' dir at any depth)
42 | **/work/**
43 | debian/prebuilt/
44 |
45 | # macOS metadata
46 | **/.DS_Store
47 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Contributing to K7
2 |
3 | Thanks for your interest in contributing!
4 |
5 | We chose a lean and minimal approach to make development on this project as simple as possible:
6 | - Infra is handled by a single Ansible playbook
7 | - The CLI and API are implemented respectively with Typer and FastAPI in Python, for simplicity. They both wrap over the same `core` module.
8 |
9 | ## Project Direction
10 |
11 | Check out the [ROADMAP.md](ROADMAP.md) to see planned features, current priorities, and long-term goals. It's a great starting point if you're looking for areas to contribute!
12 |
13 | ## Repo Layout
14 | - `src/k7/` CLI, core logic, API server
15 | - `src/katakate/` Python SDK (published to PyPI as katakate)
16 | - `src/k7/deploy/` Ansible playbook to install node
17 | - `utils/` helper scripts
18 |
19 | ## Packaging
20 | - The root Python packaging (`setup.py` and `MANIFEST.in`) builds the `katakate` SDK for PyPI only.
21 | - Assets under `src/k7/` (including `src/k7/deploy/*`) are not included in the PyPI package; they are used by the Debian/CLI packaging flow.
22 |
23 | ## Code Style
24 | - Python: PEP8, explicit types for public APIs, early returns, no inline comments
25 | - Lint/format with Ruff:
26 | - Install: `pip install ruff`
27 | - Check: `ruff check src`
28 | - Format: `ruff format src`
29 |
30 | ## Building
31 | - CLI deb helpers live in `src/k7/cli/` scripts
32 | - Make targets may be available: `make` to list
33 |
34 | ## Releases
35 | - Bump versions in `src/k7/__init__.py` and `src/katakate/__init__.py`
36 | - Tag `vX.Y.Z` to build artifacts (CI may publish .deb and wheels)
37 |
38 | ## Reporting Issues
39 | - Include steps, expected vs actual, logs, and environment (arch/OS/hardware)
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 |
2 | Apache License
3 | Version 2.0, January 2004
4 | http://www.apache.org/licenses/
5 |
6 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7 |
8 | 1. Definitions.
9 |
10 | "License" shall mean the terms and conditions for use, reproduction,
11 | and distribution as defined by Sections 1 through 9 of this document.
12 |
13 | "Licensor" shall mean the copyright owner or entity authorized by
14 | the copyright owner that is granting the License.
15 |
16 | "Legal Entity" shall mean the union of the acting entity and all
17 | other entities that control, are controlled by, or are under common
18 | control with that entity. For the purposes of this definition,
19 | "control" means (i) the power, direct or indirect, to cause the
20 | direction or management of such entity, whether by contract or
21 | otherwise, or (ii) ownership of fifty percent (50%) or more of the
22 | outstanding shares, or (iii) beneficial ownership of such entity.
23 |
24 | "You" (or "Your") shall mean an individual or Legal Entity
25 | exercising permissions granted by this License.
26 |
27 | "Source" form shall mean the preferred form for making modifications,
28 | including but not limited to software source code, documentation
29 | source, and configuration files.
30 |
31 | "Object" form shall mean any form resulting from mechanical
32 | transformation or translation of a Source form, including but
33 | not limited to compiled object code, generated documentation,
34 | and conversions to other media types.
35 |
36 | "Work" shall mean the work of authorship, whether in Source or
37 | Object form, made available under the License, as indicated by a
38 | copyright notice that is included in or attached to the work
39 | (an example is provided in the Appendix below).
40 |
41 | "Derivative Works" shall mean any work, whether in Source or Object
42 | form, that is based on (or derived from) the Work and for which the
43 | editorial revisions, annotations, elaborations, or other modifications
44 | represent, as a whole, an original work of authorship. For the purposes
45 | of this License, Derivative Works shall not include works that remain
46 | separable from, or merely link (or bind by name) to the interfaces of,
47 | the Work and Derivative Works thereof.
48 |
49 | "Contribution" shall mean any work of authorship, including
50 | the original version of the Work and any modifications or additions
51 | to that Work or Derivative Works thereof, that is intentionally
52 | submitted to Licensor for inclusion in the Work by the copyright owner
53 | or by an individual or Legal Entity authorized to submit on behalf of
54 | the copyright owner. For the purposes of this definition, "submitted"
55 | means any form of electronic, verbal, or written communication sent
56 | to the Licensor or its representatives, including but not limited to
57 | communication on electronic mailing lists, source code control systems,
58 | and issue tracking systems that are managed by, or on behalf of, the
59 | Licensor for the purpose of discussing and improving the Work, but
60 | excluding communication that is conspicuously marked or otherwise
61 | designated in writing by the copyright owner as "Not a Contribution."
62 |
63 | "Contributor" shall mean Licensor and any individual or Legal Entity
64 | on behalf of whom a Contribution has been received by Licensor and
65 | subsequently incorporated within the Work.
66 |
67 | 2. Grant of Copyright License. Subject to the terms and conditions of
68 | this License, each Contributor hereby grants to You a perpetual,
69 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70 | copyright license to reproduce, prepare Derivative Works of,
71 | publicly display, publicly perform, sublicense, and distribute the
72 | Work and such Derivative Works in Source or Object form.
73 |
74 | 3. Grant of Patent License. Subject to the terms and conditions of
75 | this License, each Contributor hereby grants to You a perpetual,
76 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77 | (except as stated in this section) patent license to make, have made,
78 | use, offer to sell, sell, import, and otherwise transfer the Work,
79 | where such license applies only to those patent claims licensable
80 | by such Contributor that are necessarily infringed by their
81 | Contribution(s) alone or by combination of their Contribution(s)
82 | with the Work to which such Contribution(s) was submitted. If You
83 | institute patent litigation against any entity (including a
84 | cross-claim or counterclaim in a lawsuit) alleging that the Work
85 | or a Contribution incorporated within the Work constitutes direct
86 | or contributory patent infringement, then any patent licenses
87 | granted to You under this License for that Work shall terminate
88 | as of the date such litigation is filed.
89 |
90 | 4. Redistribution. You may reproduce and distribute copies of the
91 | Work or Derivative Works thereof in any medium, with or without
92 | modifications, and in Source or Object form, provided that You
93 | meet the following conditions:
94 |
95 | (a) You must give any other recipients of the Work or
96 | Derivative Works a copy of this License; and
97 |
98 | (b) You must cause any modified files to carry prominent notices
99 | stating that You changed the files; and
100 |
101 | (c) You must retain, in the Source form of any Derivative Works
102 | that You distribute, all copyright, patent, trademark, and
103 | attribution notices from the Source form of the Work,
104 | excluding those notices that do not pertain to any part of
105 | the Derivative Works; and
106 |
107 | (d) If the Work includes a "NOTICE" text file as part of its
108 | distribution, then any Derivative Works that You distribute must
109 | include a readable copy of the attribution notices contained
110 | within such NOTICE file, excluding those notices that do not
111 | pertain to any part of the Derivative Works, in at least one
112 | of the following places: within a NOTICE text file distributed
113 | as part of the Derivative Works; within the Source form or
114 | documentation, if provided along with the Derivative Works; or,
115 | within a display generated by the Derivative Works, if and
116 | wherever such third-party notices normally appear. The contents
117 | of the NOTICE file are for informational purposes only and
118 | do not modify the License. You may add Your own attribution
119 | notices within Derivative Works that You distribute, alongside
120 | or as an addendum to the NOTICE text from the Work, provided
121 | that such additional attribution notices cannot be construed
122 | as modifying the License.
123 |
124 | You may add Your own copyright statement to Your modifications and
125 | may provide additional or different license terms and conditions
126 | for use, reproduction, or distribution of Your modifications, or
127 | for any such Derivative Works as a whole, provided Your use,
128 | reproduction, and distribution of the Work otherwise complies with
129 | the conditions stated in this License.
130 |
131 | 5. Submission of Contributions. Unless You explicitly state otherwise,
132 | any Contribution intentionally submitted for inclusion in the Work
133 | by You to the Licensor shall be under the terms and conditions of
134 | this License, without any additional terms or conditions.
135 | Notwithstanding the above, nothing herein shall supersede or modify
136 | the terms of any separate license agreement you may have executed
137 | with Licensor regarding such Contributions.
138 |
139 | 6. Trademarks. This License does not grant permission to use the trade
140 | names, trademarks, service marks, or product names of the Licensor,
141 | except as required for reasonable and customary use in describing the
142 | origin of the Work and reproducing the content of the NOTICE file.
143 |
144 | 7. Disclaimer of Warranty. Unless required by applicable law or
145 | agreed to in writing, Licensor provides the Work (and each
146 | Contributor provides its Contributions) on an "AS IS" BASIS,
147 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148 | implied, including, without limitation, any warranties or conditions
149 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150 | PARTICULAR PURPOSE. You are solely responsible for determining the
151 | appropriateness of using or redistributing the Work and assume any
152 | risks associated with Your exercise of permissions under this License.
153 |
154 | 8. Limitation of Liability. In no event and under no legal theory,
155 | whether in tort (including negligence), contract, or otherwise,
156 | unless required by applicable law (such as deliberate and grossly
157 | negligent acts) or agreed to in writing, shall any Contributor be
158 | liable to You for damages, including any direct, indirect, special,
159 | incidental, or consequential damages of any character arising as a
160 | result of this License or out of the use or inability to use the
161 | Work (including but not limited to damages for loss of goodwill,
162 | work stoppage, computer failure or malfunction, or any and all
163 | other commercial damages or losses), even if such Contributor
164 | has been advised of the possibility of such damages.
165 |
166 | 9. Accepting Warranty or Additional Liability. While redistributing
167 | the Work or Derivative Works thereof, You may choose to offer,
168 | and charge a fee for, acceptance of support, warranty, indemnity,
169 | or other liability obligations and/or rights consistent with this
170 | License. However, in accepting such obligations, You may act only
171 | on Your own behalf and on Your sole responsibility, not on behalf
172 | of any other Contributor, and only if You agree to indemnify,
173 | defend, and hold each Contributor harmless for any liability
174 | incurred by, or claims asserted against, such Contributor by reason
175 | of your accepting any such warranty or additional liability.
176 |
177 | END OF TERMS AND CONDITIONS
178 |
179 | APPENDIX: How to apply the Apache License to your work.
180 |
181 | To apply the Apache License to your work, attach the following
182 | boilerplate notice, with the fields enclosed by brackets "[]"
183 | replaced with your own identifying information. (Don't include
184 | the brackets!) The text should be enclosed in the appropriate
185 | comment syntax for the file format. We also recommend that a
186 | file or class name and description of purpose be included on the
187 | same "printed page" as the copyright notice for easier
188 | identification within third-party archives.
189 |
190 | Copyright [2025] [katakate.org]
191 |
192 | Licensed under the Apache License, Version 2.0 (the "License");
193 | you may not use this file except in compliance with the License.
194 | You may obtain a copy of the License at
195 |
196 | http://www.apache.org/licenses/LICENSE-2.0
197 |
198 | Unless required by applicable law or agreed to in writing, software
199 | distributed under the License is distributed on an "AS IS" BASIS,
200 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201 | See the License for the specific language governing permissions and
202 | limitations under the License.
203 |
204 |
--------------------------------------------------------------------------------
/MANIFEST.in:
--------------------------------------------------------------------------------
1 | include LICENSE
2 | include README.md
3 |
4 | # Exclude common junk
5 | global-exclude __pycache__ *.py[cod] *.so *.dylib *.dll .DS_Store .idea .vscode
--------------------------------------------------------------------------------
/Makefile:
--------------------------------------------------------------------------------
1 | SHELL := /bin/bash
2 | .SHELLFLAGS := -eu -o pipefail -c
3 |
4 | # Use sudo only when needed
5 | SUDO := $(shell command -v sudo >/dev/null 2>&1 && [ "$$(id -u)" -ne 0 ] && echo sudo)
6 |
7 | # Explicit scripts (no fallbacks)
8 | BUILD_SCRIPT := src/k7/cli/build.sh
9 | INSTALL_SCRIPT := src/k7/cli/install.sh
10 |
11 | .PHONY: help build install uninstall api-build-local api-run-local
12 |
13 | help: ## Show this help message
14 | @echo "Available targets:"
15 | @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf " \033[36m%-20s\033[0m %s\n", $$1, $$2}'
16 |
17 | build: ## Build the k7 CLI and API into .deb package
18 | @echo "Running: $(BUILD_SCRIPT)"
19 | @$(SHELL) "$(BUILD_SCRIPT)"
20 |
21 | install: ## Install the k7 CLI from built .deb package
22 | @echo "Running: $(INSTALL_SCRIPT)"
23 | @$(SHELL) "$(INSTALL_SCRIPT)"
24 | @command -v k7 >/dev/null 2>&1 && echo "Installed: $$(command -v k7)" || true
25 |
26 | uninstall: ## Uninstall the k7 CLI
27 | @echo "Running: $(INSTALL_SCRIPT) uninstall"
28 | @$(SHELL) "$(INSTALL_SCRIPT)" uninstall
29 | @echo "k7 uninstalled"
30 |
31 | api-build-local: ## Build the API container locally (dev tag)
32 | @echo "Building local API image: k7-api:dev"
33 | docker build -f src/k7/api/Dockerfile.api -t k7-api:dev .
34 |
35 | api-run-local: ## Run API using the local image (no pull)
36 | @echo "Starting API with local image (k7-api:dev)"
37 | docker pull cloudflare/cloudflared:latest || true
38 | K7_API_IMAGE=k7-api K7_API_TAG=dev k7 start-api --yes
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 |
2 |
3 | KATAKATE
4 |
5 |
6 |
7 |
8 | Self-hosted secure VM sandboxes for AI compute at scale
9 |
10 |
11 |
12 |
13 | 
14 | 
15 |
16 | 
17 |
18 |
19 |
20 |
21 |
22 |
23 | 
24 |
25 | 📸
26 |
27 | 
28 |
29 | 📸
30 |
31 | 
32 |
33 |
34 |
35 |
36 |
37 | 
38 |
39 |
40 |
41 |
42 |
43 | 
44 |
45 | 
46 | 
47 | 
48 |
49 |
50 |
51 |
52 |
53 | 
54 |
55 |
56 |
57 |
58 |
59 |
60 | Katakate aims to make it easy to create, manage and orchestrate lightweight safe VM sandboxes for executing untrusted code, at scale. It is built on battle-tested VM isolation with Kata, Firecracker and Kubernetes. It is orignally motivated by AI agents that need to run arbitrary code at scale but it is also great for:
61 | - Custom serverless (like AWS Fargate, but yours)
62 | - Hardened CI/CD runners (no Docker-in-Docker risks)
63 | - Blockchain execution layers for AI dApps
64 |
65 | > 100% open‑source (Apache‑2.0). For technical support, write us at: hi@katakate.org
66 |
67 |
68 | The Tech Stack
69 |
70 |
71 | Katakate is built on:
72 | - Kubernetes for orchestration, with K3s which is prod-ready and a great choice for edge nodes,
73 | - Kata to encapsulate containers into light-weight virtual-machines,
74 | - Firecracker as the chosen VM, for super-fast boots, light footprints and minimal attack surface,
75 | - Devmapper Snapshotter with thin-pool provisioning of logical volumes for efficient use of disk space shared by dozens of VMs per node.
76 |
77 |
78 |
79 | Coming Soon
80 |
81 |
82 |
83 | - 🛠️ Docker build / run / compose support inside the VM sandbox
84 | - 🌐 Multi-node cluster capabilities for distributed workloads
85 | - 🔍 Cilium FQDN-based DNS resolution to safely whitelist domains, not just IP blocks
86 | - ⚙️ Support other VMM such as Qemu for GPU workloads
87 |
88 | 📋 **See [ROADMAP.md](ROADMAP.md) for the complete feature roadmap and project priorities.**
89 |
90 |
91 |
92 | Note: Katakate is currently in beta and under security review. Use with caution for highly sensitive workloads.
93 |
94 |
95 |
96 | # Usage
97 |
98 | For usage you need:
99 | - **Node(s)** that will host the VM sandboxes
100 | - **Client** from where to send requests
101 |
102 | We provide a:
103 |
104 | - **CLI**: to use on the node(s) directly --> `apt install k7`
105 | - **API**: deployed on the (master) node(s) --> `k7 start-api`
106 | - **Python SDK**: Python client sync/async talking to API --> `pip install katakate`
107 |
108 | ## Current requirements
109 |
110 | ### For the node(s)
111 |
112 | - Ubuntu (amd64) host.
113 | - Hardware virtualization (KVM) available and accessible
114 | - Check: `ls /dev/kvm` should exist.
115 | - This is typically available on your own Linux machine.
116 | - On cloud providers, it varies.
117 | - Hetzner (the only one I tested so far) yes for their `Robot` instances only, i.e. "dedicated": robot.hetzner.com.
118 | - AWS: only `.metal` EC2 instances.
119 | - GCP: virtualization friendly, most instances, with `--enable-nested-virtualization` flag.
120 | - Azure: Dv3, Ev3, Dv4, Ev4, Dv5, Ev5. Must be Intel/AMD x86, not ARM.
121 | - DigitalOcean: Premium Intel and AMD droplets with nested virtualization enabled.
122 | - Others: in general, hardware virtualization is not exposed on cloud VPS, so you'll likely want a dedicated / bare metal.
123 | - One raw disk (unformatted, unpartitioned) for the thin-pool that k7 will provision for efficient disk usage of sandboxes.
124 | - Use `./utils/wipe-disk.sh /your/disk` to wipe a disk clean before provisioning. DANGER: destructive - it will remove data/partitions/formatting/SWRAID.
125 | - Ansible (for installer):
126 | ```bash
127 | sudo add-apt-repository universe -y
128 | sudo apt update
129 | sudo apt install -y ansible
130 | ```
131 | - Docker and Docker Compose (for the API):
132 | ```bash
133 | curl -fsSL https://get.docker.com | sh
134 | ```
135 |
136 | Already tested setups:
137 | - Hetzner Robot instance with Ubuntu 24.04, x86_64 arch, booked with 1 extra empty disk `nvme2n1` for the thin-pool provisioning. See the setup guide (PDF): [tutorials/k7_hetzner_node_setup.pdf](tutorials/k7_hetzner_node_setup.pdf).
138 |
139 | ### For the client
140 |
141 | Just recent Python.
142 |
143 | ## Quick Start
144 |
145 |
146 | ### Get your node(s) ready
147 |
148 | First install `k7` on your Linux server that will host the VMs:
149 | ```shell
150 | sudo add-apt-repository ppa:katakate.org/k7
151 | sudo apt update
152 | sudo apt install k7
153 | ```
154 |
155 |
156 | Then let `k7` get your node ready with everything:
157 | ```console
158 | $ k7 install
159 | Current task: Reminder about logging out and back in for group changes
160 | Installing K7 on 1 host(s)... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:01:41
161 | ✅ Installation completed successfully!
162 |
163 | ```
164 |
165 | Optionally pass `-v` for a verbose output.
166 |
167 | This will install and most importantly connect together the following components:
168 | - Kubernetes (K3s prod-ready distribution)
169 | - Kata (for container virtualization)
170 | - Firecracker (as Virtual Machine Manager)
171 | - Jailer (to secure Firecracker VMs further into a chroot)
172 | - devmapper snapshotter with thin-pool provisioning of logical volumes for VM efficient disk memory usage
173 |
174 |
175 | Careful design: config updates will not touch your existing Docker or containerd setups. We chose to use K3s' own containerd for minimal disruption. Installation may however overwrite existing installations of K3s, Kata, Firecracker, Jailer.
176 |
177 | ### CLI Usage
178 |
179 | You can run workloads directly from the node(s) using the CLI. To create a sandbox, just create a yaml config for it.
180 |
181 | #### k7.yaml example:
182 |
183 | ```yaml
184 | name: my-sandbox-123
185 | image: alpine:latest
186 | namespace: default
187 |
188 | # Optional: restrict egress
189 | egress_whitelist:
190 | - "1.1.1.1/32" # Cloudflare DNS
191 | - "8.8.8.8/32" # Google DNS
192 |
193 | # Optional: resource limits
194 | limits:
195 | cpu: "1"
196 | memory: "1Gi"
197 | ephemeral-storage: "2Gi"
198 |
199 | # Optional: run before_script inside the container once at start. Network restrictions apply after the before-script, so you can install packages here, pull git repos, etc
200 | before_script: |
201 | apk add --no-cache git curl
202 |
203 | # Optional: load environment variables from a file. These will be available both during the before-script, and in the sandbox
204 | env_file: path/to/your/secrets/.env
205 | ```
206 |
207 |
208 | #### Running commands
209 |
210 |
211 | ```bash
212 | # Create a sandbox (uses k7.yaml in the current directory by default, but you can also pass: -f myfile.yaml)
213 | k7 create
214 |
215 | # List sandboxes
216 | k7 list
217 |
218 | # Delete a sandbox
219 | k7 delete my-sandbox-123
220 |
221 | # Delete all sandboxes. You can also pass a namespace
222 | k7 delete-all
223 | ```
224 |
225 | ### API usage
226 |
227 | If you'd like to manage workloads remotely, just use the API:
228 |
229 | ```shell
230 | # Start API server (containerized and SSL support with Cloudflared)
231 | k7 start-api
232 |
233 | # Generate API key
234 | k7 generate-api-key my-key1
235 | ```
236 |
237 | Make sure your user is in the `Docker` group to be allowed to start or stop the API.
238 |
239 | As for generating / listing / revoking keys, you might need `sudo` or `root`.
240 |
241 | ### Python SDK Usage
242 |
243 | After your k7 API is up, usage is very simple.
244 |
245 | Install the Python SDK via:
246 | ```shell
247 | pip install katakate
248 | ```
249 |
250 | Or if you want async support:
251 | ```shell
252 | pip install "katakate[async-sdk]"
253 | ```
254 |
255 | Then use with:
256 | ```python
257 | from katakate import Client
258 |
259 | k7 = Client(
260 | endpoint='https://',
261 | api_key='your-key')
262 |
263 | # Create sandbox
264 | sb = k7.create({
265 | "name": "my-sandbox",
266 | "image": "alpine:latest"
267 | })
268 |
269 | # Execute code
270 | result = sb.exec('echo "Hello World"')
271 | print(result['stdout'])
272 |
273 | # List all sandboxes
274 | sandboxes = k7.list()
275 |
276 | # Delete sandbox
277 | sb.delete()
278 | ```
279 |
280 | #### Async variant
281 | ```python
282 | import asyncio
283 | from katakate import AsyncClient
284 |
285 | async def main():
286 | k7 = AsyncClient(
287 | endpoint='https://',
288 | api_key='your-key'
289 | )
290 | print(await k7.list())
291 | await k7.aclose()
292 |
293 | asyncio.run(main())
294 | ```
295 |
296 |
297 | ### Tutorials
298 |
299 | - LangChain ReAct agent with a K7 sandbox tool
300 | - Path: tutorials/langchain-react-agent
301 | - Setup: copy .env.example to .env and fill K7_ENDPOINT/K7_API_KEY/OPENAI_API_KEY
302 | - Run: python agent.py
303 | - Try asking it anything! e.g. "List files from '/'"
304 |
305 | ## Build from source
306 |
307 |
308 | First install make if not already available:
309 | ```bash
310 | sudo add-apt-repository universe -y
311 | sudo apt update
312 | sudo apt install make
313 | ```
314 |
315 |
316 | To build the `k7` CLI and API into `.deb` package:
317 | ```shell
318 | make build
319 | ```
320 |
321 | You can then install it with:
322 | ```shell
323 | sudo make install
324 | ```
325 |
326 | To uninstall later:
327 | ```shell
328 | sudo make uninstall
329 | ```
330 |
331 | Note: we recommend running `make uninstall` before reinstalling if it is not your first install, to avoid stale copies of cached files in the .deb package.
332 |
333 |
334 | ### Build and run the API container
335 |
336 | Local dev image:
337 | ```bash
338 | # Build the API image locally
339 | make api-build-local
340 |
341 | # Run API using local image (no pull)
342 | make api-run-local
343 | ```
344 |
345 |
346 | ### Build the katakate Python SDK from source
347 |
348 | Preferred (uv):
349 |
350 | ```bash
351 | # create env
352 | uv venv .venv-build
353 | . .venv-build/bin/activate
354 |
355 | # install directly from source in editable mode
356 | uv pip install -e .
357 | ```
358 |
359 |
360 | ## Security
361 |
362 | K7 sandboxes are hardened by default with multiple layers of security:
363 |
364 | - **VM isolation**: Kata Containers provide hardware-level isolation via lightweight VMs with Firecracker
365 | - VMs are further restricted into a chroot using Jailer
366 | - Kata's Seccomp restrictions are enabled
367 |
368 | - **Linux capabilities**: All capabilities are dropped by default (`drop: ALL`) for defense-in-depth
369 | - Only explicitly add back capabilities you need via `cap_add` parameter
370 | - `allow_privilege_escalation` is always set to `false`
371 | - Seccomp profile: `RuntimeDefault`
372 |
373 | - **Non-root execution**: Optionally run containers and pods as non-root user (UID 65532):
374 | - `container_non_root`: Run the main container as non-root and disable privilege escalation
375 | - `pod_non_root`: Run the entire pod as non-root with consistent filesystem ownership (UID/GID/FSGroup 65532)
376 |
377 | - **API security**:
378 | - API keys stored as SHA256 hashes with timing-attack-resistant comparison
379 | - Expiry enforced; last-used timestamp recorded
380 | - File-based storage with 600 permissions (`/etc/k7/api_keys.json` by default)
381 |
382 | - **Network policies**: Complete network isolation for VM sandboxes
383 | - **Ingress isolation**: All inter-VM communication is blocked by default to prevent sandbox-to-sandbox access
384 | - **Egress lockdown**: Control outbound traffic with CIDR-based restrictions using Kubernetes NetworkPolicies
385 | - DNS to CoreDNS always allowed when egress is locked down
386 | - Administrative access via `kubectl exec` and `k7 shell` is preserved (uses Kubernetes API, not pod networking)
387 | - Soon to come: Cilium integration for domain name whitelisting
388 |
389 | More security features are currently on the roadmap, including integrating AppArmor.
390 |
391 | ## Packaging & Releases
392 |
393 | - Layout uses `src/`:
394 | - CLI, API, core live under `src/k7/`
395 | - SDK under `src/katakate/`
396 | - Root packaging targets the `katakate` SDK only; assets under `src/k7/` are not part of the PyPI distribution.
397 | - `MANIFEST.in` (for the `katakate` SDK) should include essentials like `LICENSE` and `README.md` only; deploy assets from `src/k7/deploy/*` belong to the Debian/CLI packaging flow, not to the PyPI package.
398 | - `setup.py` for `katakate` lives at repo root; packages from `src/`.
399 | - The CLI Debian package is built via `src/k7/cli/build.sh` and produces `dist/k7__amd64.deb`.
400 | - CI (tags `v*`) can publish the PyPI SDK and upload the `.deb` artifact.
401 |
402 |
403 |
404 | ## Known issues
405 |
406 | - Jailer seems to be currently ignored by Kata despite being passed correctly into its configuration, and despite the Jailer process being started. The use of Kubernetes secrets could be a reason of incompatibility. This is under investigation.
--------------------------------------------------------------------------------
/ROADMAP.md:
--------------------------------------------------------------------------------
1 | # 🗺️ Project Roadmap
2 |
3 | This document outlines the upcoming milestones, goals, and long-term vision for **K7**.
4 | It helps contributors and users understand where the project is heading.
5 |
6 | ---
7 |
8 | ## 🚀 Current Focus
9 |
10 | Core stability and foundational runtime improvements.
11 |
12 | - [ ] Add `--disk` argument to `k7 install` to specify external disk path explicitly for thin pool provisioning, and test it
13 | - [ ] Test if removing DNS resolution completely doesn't break functionality (to protect against DNS exfiltration)
14 | - [ ] Add pause/resume support for sandboxes
15 | - [ ] Fix jailer functionality (known issue)
16 | - [ ] Add multi-node support (currently single K3s node supported)
17 |
18 |
19 |
20 | ---
21 |
22 | ## 🧩 Next Goals
23 |
24 | Broader compatibility and container integration.
25 |
26 | - [ ] Add ARM support for Linux Debian
27 | - [ ] Add Docker build / run / compose capabilities in VM sandboxes (major feature!)
28 | - [ ] Integrate Cilium networking
29 | - [ ] Implement Docker pull deny/whitelist
30 |
31 | ---
32 |
33 | ## ⚙️ Future Work
34 |
35 | Cross-platform support and continuous delivery.
36 |
37 | - [ ] Add QEMU support (macOS ARM, GPU support)
38 | - [ ] Add AppArmor integration
39 | - [ ] Add CI/CD and deployment tests
40 |
41 | ---
42 |
43 | ## 🔐 Advanced Features
44 |
45 | Security, customization, and extended runtime capabilities.
46 |
47 | - [ ] Add TEE (Trusted Execution Environment) support
48 | - [ ] Add custom rootfs support (lighter, alternative images)
49 |
50 | ---
51 |
52 | ## 💬 How to Contribute
53 |
54 | We welcome ideas and feedback!
55 | If you'd like to suggest a feature or help with one listed above:
56 | 1. Open a [Discussion](https://github.com/katakate/k7/discussions) or [Issue](https://github.com/katakate/k7/issues)
57 | 2. Reference the relevant roadmap item
58 | 3. Let's collaborate on the design or implementation
59 |
60 | ---
61 |
62 | 📅 *Last updated: October 2025*
63 |
--------------------------------------------------------------------------------
/SECURITY.md:
--------------------------------------------------------------------------------
1 | # Security Policy
2 |
3 | ## Supported Versions
4 |
5 | This project is pre-1.0 (currently 0.0.1) and under active development and security hardening. Breaking changes may occur between minor versions until 1.0.0.
6 |
7 | ## Reporting a Vulnerability
8 |
9 | If you believe you have found a security vulnerability, please email:
10 |
11 | - security@katakate.org (preferred)
12 | - Or open a private security advisory via GitHub (Security → Advisories → Report a vulnerability)
13 |
14 | Please include:
15 | - A detailed description of the issue and potential impact
16 | - Steps to reproduce or proof-of-concept
17 | - Affected versions/commit SHAs and environment details
18 |
19 | We aim to acknowledge reports within 72 hours and provide a remediation plan or mitigation timeline when applicable.
20 |
21 | ## Scope and Current Model
22 |
23 | - Nodes run K3s + Kata + Firecracker; containers run as non-root with restricted capabilities.
24 | - API uses API keys with hashed storage and expiry; file-backed by default.
25 | - Egress network restrictions via Kubernetes NetworkPolicies (IP-based whitelists). DNS to kube-dns is allowed for name resolution only.
26 | - All ingress network blocked by default to avoid default K8s pod to pod communications; this doesn't affect kubectl exec / k7 shell into sandboxes which are based on the k8s API.
27 |
28 | Known limitations (pre-0.1.0):
29 |
30 | - No rate limiting or abuse protection at API layer yet.
31 | - API key storage is local file; rotate and protect `/etc/k7/api_keys.json`.
32 | - No domain-based egress control (planned via Cilium/FQDN policies).
33 | - Jailer currently ignored by Kata
34 | - Only single-node supported right now, multi-node support high on the roadmap
35 | - We might want to get rid of the compose setup for the API and instead directly deploy the API on the K3s cluster by writing a few manifests.
36 | - If keeping API out-of-cluster we should rather pass to the API a dedicated RBAC restricted Kube config instead of the admin config.
37 |
38 | ## Responsible Disclosure
39 |
40 | Do not publicly disclose vulnerabilities before we have had a reasonable time to investigate and release fixes. We appreciate coordinated disclosure and will credit reporters unless anonymity is requested.
--------------------------------------------------------------------------------
/assets/demo-k7.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Katakate/k7/f48ae38b9aeeec52e50aad8f157451b10e5ffc65/assets/demo-k7.gif
--------------------------------------------------------------------------------
/assets/k7-console-dev.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Katakate/k7/f48ae38b9aeeec52e50aad8f157451b10e5ffc65/assets/k7-console-dev.png
--------------------------------------------------------------------------------
/assets/k7-cover-upgrade.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Katakate/k7/f48ae38b9aeeec52e50aad8f157451b10e5ffc65/assets/k7-cover-upgrade.png
--------------------------------------------------------------------------------
/assets/show-hn_nb1_post-id-45656952.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Katakate/k7/f48ae38b9aeeec52e50aad8f157451b10e5ffc65/assets/show-hn_nb1_post-id-45656952.png
--------------------------------------------------------------------------------
/debian/changelog:
--------------------------------------------------------------------------------
1 | k7 (0.0.3) noble; urgency=medium
2 |
3 | * Fix Docker image name to use lowercase (ghcr.io/katakate/k7-api)
4 |
5 | -- root Sun, 28 Sep 2025 23:52:10 +0200
6 |
7 | k7 (0.0.2) noble; urgency=medium
8 |
9 | * Fix Kata Containers download to support both .tar.zst and .tar.xz
10 | formats
11 |
12 | -- root Sun, 28 Sep 2025 23:02:04 +0200
13 |
14 | k7 (0.0.1) noble; urgency=medium
15 |
16 | * Initial packaging for PPA builds.
17 |
18 | -- K7 Team Mon, 22 Sep 2025 00:00:00 +0000
19 |
20 |
21 |
--------------------------------------------------------------------------------
/debian/clean:
--------------------------------------------------------------------------------
1 | dist/
2 | build/
3 | .nuitka-cache/
4 | *.build
5 | *.dist
6 |
7 |
--------------------------------------------------------------------------------
/debian/control:
--------------------------------------------------------------------------------
1 | Source: k7
2 | Section: utils
3 | Priority: optional
4 | Maintainer: K7 Team
5 | Build-Depends: debhelper-compat (= 13),
6 | dh-python,
7 | python3,
8 | python3-dev,
9 | nuitka,
10 | patchelf,
11 | python3-typer,
12 | python3-kubernetes,
13 | python3-dotenv,
14 | python3-yaml,
15 | python3-rich
16 | Standards-Version: 4.6.2
17 | Homepage: https://katakate.org
18 | Rules-Requires-Root: no
19 |
20 | Package: k7
21 | Architecture: amd64
22 | Depends: ${shlibs:Depends}, ${misc:Depends}
23 | Recommends: docker.io, docker-compose-plugin, kubectl | k3s, ansible
24 | Description: K7 CLI for sandbox management
25 | Provides the `k7` command with embedded installer playbook.
26 |
27 |
28 |
29 |
30 |
--------------------------------------------------------------------------------
/debian/copyright:
--------------------------------------------------------------------------------
1 | Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
2 | Upstream-Name: k7
3 | Source: https://github.com/Katakate/katakate
4 |
5 | Files: *
6 | Copyright: 2025 Katakate Authors
7 | License: Apache-2.0
8 | Licensed under the Apache License, Version 2.0 (the "License");
9 | you may not use this file except in compliance with the License.
10 | You may obtain a copy of the License at
11 | .
12 | http://www.apache.org/licenses/LICENSE-2.0
13 | .
14 | Unless required by applicable law or agreed to in writing, software
15 | distributed under the License is distributed on an "AS IS" BASIS,
16 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17 | See the License for the specific language governing permissions and
18 | limitations under the License.
19 |
20 | Files: LICENSE
21 | Copyright: 2025 Katakate Authors
22 | License: Apache-2.0
23 | The full text of the Apache-2.0 license is distributed in the file
24 | /usr/share/common-licenses/Apache-2.0 or at:
25 | .
26 | http://www.apache.org/licenses/LICENSE-2.0
27 |
28 |
29 |
30 |
31 |
32 |
--------------------------------------------------------------------------------
/debian/k7.install:
--------------------------------------------------------------------------------
1 | dist/k7 usr/bin/
2 |
3 |
4 |
5 |
6 |
--------------------------------------------------------------------------------
/debian/rules:
--------------------------------------------------------------------------------
1 | #!/usr/bin/make -f
2 | %:
3 | dh $@
4 |
5 | override_dh_auto_build:
6 | mkdir -p dist
7 | if [ -f debian/prebuilt/k7 ]; then \
8 | echo "Using prebuilt debian/prebuilt/k7"; \
9 | cp debian/prebuilt/k7 dist/k7; \
10 | chmod 0755 dist/k7; \
11 | elif [ -f dist/k7 ]; then \
12 | echo "Using prebuilt dist/k7"; \
13 | chmod 0755 dist/k7; \
14 | else \
15 | if command -v docker >/dev/null 2>&1; then \
16 | echo "Building k7 binary via Docker (src/k7/cli/Dockerfile.cli)..."; \
17 | docker build --platform=linux/amd64 -t k7-cli-builder -f src/k7/cli/Dockerfile.cli .; \
18 | cid=$$(docker create --platform=linux/amd64 k7-cli-builder); \
19 | docker cp "$$cid":/app/k7.bin ./dist/k7 || docker cp "$$cid":/app/k7.cli.bin ./dist/k7; \
20 | docker rm -v "$$cid" >/dev/null; \
21 | chmod 0755 dist/k7; \
22 | else \
23 | echo "Docker not available; building via local Nuitka..."; \
24 | python3 -m nuitka \
25 | --standalone --onefile \
26 | --include-module=yaml \
27 | --include-module=rich \
28 | --include-module=typer \
29 | --include-module=kubernetes \
30 | --include-module=dotenv \
31 | --include-data-dir=src/k7=k7 \
32 | src/k7/cli/k7.py; \
33 | if [ -f k7.bin ]; then mv k7.bin dist/k7; \
34 | elif [ -f k7.cli.bin ]; then mv k7.cli.bin dist/k7; \
35 | else echo "Nuitka output not found"; exit 1; fi; \
36 | chmod 0755 dist/k7; \
37 | fi; \
38 | fi
39 |
40 | override_dh_auto_clean:
41 | rm -rf dist build .nuitka-cache *.build *.dist
42 |
43 | override_dh_auto_install:
44 | # Use dh_install via debian/k7.install; do not run project Makefile install
45 | true
46 |
47 | override_dh_strip:
48 | # Do not strip the Nuitka onefile; payload is appended to the ELF
49 | true
50 |
51 | override_dh_dwz:
52 | # Do not run dwz on the onefile binary
53 | true
54 |
--------------------------------------------------------------------------------
/debian/source/format:
--------------------------------------------------------------------------------
1 | 3.0 (native)
2 |
3 |
4 |
5 |
6 |
--------------------------------------------------------------------------------
/debian/source/options:
--------------------------------------------------------------------------------
1 | extend-diff-ignore = "(^|/)(\.venv(|-.*)/|venv(|-.*)/|k7\.build/|k7\.dist/|k7\.onefile-build/|dist/|build/).*"
2 | tar-ignore = .git
3 | tar-ignore = .venv
4 | tar-ignore = .venv-*
5 | tar-ignore = .venv-build
6 | tar-ignore = .venv-k7sdk
7 | tar-ignore = venv
8 | tar-ignore = venv-*
9 | tar-ignore = k7.build
10 | tar-ignore = k7.dist
11 | tar-ignore = k7.onefile-build
12 | tar-ignore = dist
13 | tar-ignore = build
14 |
15 |
--------------------------------------------------------------------------------
/docs/README.md:
--------------------------------------------------------------------------------
1 | # Katakate Docs
2 |
3 | This directory contains the Mintlify site for the Katakate project (k7 CLI, API, and Python SDK).
4 |
5 | Run locally:
6 |
7 | ```
8 | npm i -g mint
9 | mint dev
10 | ```
11 |
12 | ## Development
13 |
14 | Install the [Mintlify CLI](https://www.npmjs.com/package/mint) to preview your documentation changes locally. To install, use the following command:
15 |
16 | ```
17 | npm i -g mint
18 | ```
19 |
20 | Run the following command at the root of your documentation, where your `docs.json` is located:
21 |
22 | ```
23 | mint dev
24 | ```
25 |
26 | View your local preview at `http://localhost:3000`.
27 |
28 | ## Publishing changes
29 |
30 | Install our GitHub app from your [dashboard](https://dashboard.mintlify.com/settings/organization/github-app) to propagate changes from your repo to your deployment. Changes are deployed to production automatically after pushing to the default branch.
31 |
32 | ## Need help?
33 |
34 | ### Troubleshooting
35 |
36 | - If your dev environment isn't running: Run `mint update` to ensure you have the most recent version of the CLI.
37 | - If a page loads as a 404: Make sure you are running in a folder with a valid `docs.json`.
38 |
39 | ### Resources
40 | - [Mintlify documentation](https://mintlify.com/docs)
41 | - [Mintlify community](https://mintlify.com/community)
42 |
--------------------------------------------------------------------------------
/docs/ai-tools/claude-code.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Claude Code setup"
3 | description: "Configure Claude Code for your documentation workflow"
4 | icon: "asterisk"
5 | ---
6 |
7 | Claude Code is Anthropic's official CLI tool. This guide will help you set up Claude Code to help you write and maintain your documentation.
8 |
9 | ## Prerequisites
10 |
11 | - Active Claude subscription (Pro, Max, or API access)
12 |
13 | ## Setup
14 |
15 | 1. Install Claude Code globally:
16 |
17 | ```bash
18 | npm install -g @anthropic-ai/claude-code
19 | ```
20 |
21 | 2. Navigate to your docs directory.
22 | 3. (Optional) Add the `CLAUDE.md` file below to your project.
23 | 4. Run `claude` to start.
24 |
25 | ## Create `CLAUDE.md`
26 |
27 | Create a `CLAUDE.md` file at the root of your documentation repository to train Claude Code on your specific documentation standards:
28 |
29 | ````markdown
30 | # Mintlify documentation
31 |
32 | ## Working relationship
33 | - You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
34 | - ALWAYS ask for clarification rather than making assumptions
35 | - NEVER lie, guess, or make up information
36 |
37 | ## Project context
38 | - Format: MDX files with YAML frontmatter
39 | - Config: docs.json for navigation, theme, settings
40 | - Components: Mintlify components
41 |
42 | ## Content strategy
43 | - Document just enough for user success - not too much, not too little
44 | - Prioritize accuracy and usability of information
45 | - Make content evergreen when possible
46 | - Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
47 | - Check existing patterns for consistency
48 | - Start by making the smallest reasonable changes
49 |
50 | ## Frontmatter requirements for pages
51 | - title: Clear, descriptive page title
52 | - description: Concise summary for SEO/navigation
53 |
54 | ## Writing standards
55 | - Second-person voice ("you")
56 | - Prerequisites at start of procedural content
57 | - Test all code examples before publishing
58 | - Match style and formatting of existing pages
59 | - Include both basic and advanced use cases
60 | - Language tags on all code blocks
61 | - Alt text on all images
62 | - Relative paths for internal links
63 |
64 | ## Git workflow
65 | - NEVER use --no-verify when committing
66 | - Ask how to handle uncommitted changes before starting
67 | - Create a new branch when no clear branch exists for changes
68 | - Commit frequently throughout development
69 | - NEVER skip or disable pre-commit hooks
70 |
71 | ## Do not
72 | - Skip frontmatter on any MDX file
73 | - Use absolute URLs for internal links
74 | - Include untested code examples
75 | - Make assumptions - always ask for clarification
76 | ````
77 |
--------------------------------------------------------------------------------
/docs/ai-tools/cursor.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Cursor setup"
3 | description: "Configure Cursor for your documentation workflow"
4 | icon: "arrow-pointer"
5 | ---
6 |
7 | Use Cursor to help write and maintain your documentation for Katakate. This guide shows how to configure Cursor for better results on technical writing tasks and using Mintlify components.
8 |
9 | ## Prerequisites
10 |
11 | - Cursor editor installed
12 | - Access to your documentation repository
13 |
14 | ## Project rules
15 |
16 | Create project rules that all team members can use. In your documentation repository root:
17 |
18 | ```bash
19 | mkdir -p .cursor
20 | ```
21 |
22 | Create `.cursor/rules.md`:
23 |
24 | ````markdown
25 | # Mintlify technical writing rule
26 |
27 | You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.
28 |
29 | ## Core writing principles
30 |
31 | ### Language and style requirements
32 |
33 | - Use clear, direct language appropriate for technical audiences
34 | - Write in second person ("you") for instructions and procedures
35 | - Use active voice over passive voice
36 | - Employ present tense for current states, future tense for outcomes
37 | - Avoid jargon unless necessary and define terms when first used
38 | - Maintain consistent terminology throughout all documentation
39 | - Keep sentences concise while providing necessary context
40 | - Use parallel structure in lists, headings, and procedures
41 |
42 | ### Content organization standards
43 |
44 | - Lead with the most important information (inverted pyramid structure)
45 | - Use progressive disclosure: basic concepts before advanced ones
46 | - Break complex procedures into numbered steps
47 | - Include prerequisites and context before instructions
48 | - Provide expected outcomes for each major step
49 | - Use descriptive, keyword-rich headings for navigation and SEO
50 | - Group related information logically with clear section breaks
51 |
52 | ### User-centered approach
53 |
54 | - Focus on user goals and outcomes rather than system features
55 | - Anticipate common questions and address them proactively
56 | - Include troubleshooting for likely failure points
57 | - Write for scannability with clear headings, lists, and white space
58 | - Include verification steps to confirm success
59 |
60 | ## Mintlify component reference
61 |
62 | ### Callout components
63 |
64 | #### Note - Additional helpful information
65 |
66 |
67 | Supplementary information that supports the main content without interrupting flow
68 |
69 |
70 | #### Tip - Best practices and pro tips
71 |
72 |
73 | Expert advice, shortcuts, or best practices that enhance user success
74 |
75 |
76 | #### Warning - Important cautions
77 |
78 |
79 | Critical information about potential issues, breaking changes, or destructive actions
80 |
81 |
82 | #### Info - Neutral contextual information
83 |
84 |
85 | Background information, context, or neutral announcements
86 |
87 |
88 | #### Check - Success confirmations
89 |
90 |
91 | Positive confirmations, successful completions, or achievement indicators
92 |
93 |
94 | ### Code components
95 |
96 | #### Single code block
97 |
98 | Example of a single code block:
99 |
100 | ```javascript config.js
101 | const apiConfig = {
102 | baseURL: 'https://api.example.com',
103 | timeout: 5000,
104 | headers: {
105 | 'Authorization': `Bearer ${process.env.API_TOKEN}`
106 | }
107 | };
108 | ```
109 |
110 | #### Code group with multiple languages
111 |
112 | Example of a code group:
113 |
114 |
115 | ```javascript Node.js
116 | const response = await fetch('/api/endpoint', {
117 | headers: { Authorization: `Bearer ${apiKey}` }
118 | });
119 | ```
120 |
121 | ```python Python
122 | import requests
123 | response = requests.get('/api/endpoint',
124 | headers={'Authorization': f'Bearer {api_key}'})
125 | ```
126 |
127 | ```curl cURL
128 | curl -X GET '/api/endpoint' \
129 | -H 'Authorization: Bearer YOUR_API_KEY'
130 | ```
131 |
132 |
133 | #### Request/response examples
134 |
135 | Example of request/response documentation:
136 |
137 |
138 | ```bash cURL
139 | curl -X POST 'https://api.example.com/users' \
140 | -H 'Content-Type: application/json' \
141 | -d '{"name": "John Doe", "email": "john@example.com"}'
142 | ```
143 |
144 |
145 |
146 | ```json Success
147 | {
148 | "id": "user_123",
149 | "name": "John Doe",
150 | "email": "john@example.com",
151 | "created_at": "2024-01-15T10:30:00Z"
152 | }
153 | ```
154 |
155 |
156 | ### Structural components
157 |
158 | #### Steps for procedures
159 |
160 | Example of step-by-step instructions:
161 |
162 |
163 |
164 | Run `npm install` to install required packages.
165 |
166 |
167 | Verify installation by running `npm list`.
168 |
169 |
170 |
171 |
172 | Create a `.env` file with your API credentials.
173 |
174 | ```bash
175 | API_KEY=your_api_key_here
176 | ```
177 |
178 |
179 | Never commit API keys to version control.
180 |
181 |
182 |
183 |
184 | #### Tabs for alternative content
185 |
186 | Example of tabbed content:
187 |
188 |
189 |
190 | ```bash
191 | brew install node
192 | npm install -g package-name
193 | ```
194 |
195 |
196 |
197 | ```powershell
198 | choco install nodejs
199 | npm install -g package-name
200 | ```
201 |
202 |
203 |
204 | ```bash
205 | sudo apt install nodejs npm
206 | npm install -g package-name
207 | ```
208 |
209 |
210 |
211 | #### Accordions for collapsible content
212 |
213 | Example of accordion groups:
214 |
215 |
216 |
217 | - **Firewall blocking**: Ensure ports 80 and 443 are open
218 | - **Proxy configuration**: Set HTTP_PROXY environment variable
219 | - **DNS resolution**: Try using 8.8.8.8 as DNS server
220 |
221 |
222 |
223 | ```javascript
224 | const config = {
225 | performance: { cache: true, timeout: 30000 },
226 | security: { encryption: 'AES-256' }
227 | };
228 | ```
229 |
230 |
231 |
232 | ### Cards and columns for emphasizing information
233 |
234 | Example of cards and card groups:
235 |
236 |
237 | Complete walkthrough from installation to your first API call in under 10 minutes.
238 |
239 |
240 |
241 |
242 | Learn how to authenticate requests using API keys or JWT tokens.
243 |
244 |
245 |
246 | Understand rate limits and best practices for high-volume usage.
247 |
248 |
249 |
250 | ### API documentation components
251 |
252 | #### Parameter fields
253 |
254 | Example of parameter documentation:
255 |
256 |
257 | Unique identifier for the user. Must be a valid UUID v4 format.
258 |
259 |
260 |
261 | User's email address. Must be valid and unique within the system.
262 |
263 |
264 |
265 | Maximum number of results to return. Range: 1-100.
266 |
267 |
268 |
269 | Bearer token for API authentication. Format: `Bearer YOUR_API_KEY`
270 |
271 |
272 | #### Response fields
273 |
274 | Example of response field documentation:
275 |
276 |
277 | Unique identifier assigned to the newly created user.
278 |
279 |
280 |
281 | ISO 8601 formatted timestamp of when the user was created.
282 |
283 |
284 |
285 | List of permission strings assigned to this user.
286 |
287 |
288 | #### Expandable nested fields
289 |
290 | Example of nested field documentation:
291 |
292 |
293 | Complete user object with all associated data.
294 |
295 |
296 |
297 | User profile information including personal details.
298 |
299 |
300 |
301 | User's first name as entered during registration.
302 |
303 |
304 |
305 | URL to user's profile picture. Returns null if no avatar is set.
306 |
307 |
308 |
309 |
310 |
311 |
312 | ### Media and advanced components
313 |
314 | #### Frames for images
315 |
316 | Wrap all images in frames:
317 |
318 |
319 | 
320 |
321 |
322 |
323 | 
324 |
325 |
326 | #### Videos
327 |
328 | Use the HTML video element for self-hosted video content:
329 |
330 |
335 |
336 | Embed YouTube videos using iframe elements:
337 |
338 |
346 |
347 | #### Tooltips
348 |
349 | Example of tooltip usage:
350 |
351 |
352 | API
353 |
354 |
355 | #### Updates
356 |
357 | Use updates for changelogs:
358 |
359 |
360 | ## New features
361 | - Added bulk user import functionality
362 | - Improved error messages with actionable suggestions
363 |
364 | ## Bug fixes
365 | - Fixed pagination issue with large datasets
366 | - Resolved authentication timeout problems
367 |
368 |
369 | ## Required page structure
370 |
371 | Every documentation page must begin with YAML frontmatter:
372 |
373 | ```yaml
374 | ---
375 | title: "Clear, specific, keyword-rich title"
376 | description: "Concise description explaining page purpose and value"
377 | ---
378 | ```
379 |
380 | ## Content quality standards
381 |
382 | ### Code examples requirements
383 |
384 | - Always include complete, runnable examples that users can copy and execute
385 | - Show proper error handling and edge case management
386 | - Use realistic data instead of placeholder values
387 | - Include expected outputs and results for verification
388 | - Test all code examples thoroughly before publishing
389 | - Specify language and include filename when relevant
390 | - Add explanatory comments for complex logic
391 | - Never include real API keys or secrets in code examples
392 |
393 | ### API documentation requirements
394 |
395 | - Document all parameters including optional ones with clear descriptions
396 | - Show both success and error response examples with realistic data
397 | - Include rate limiting information with specific limits
398 | - Provide authentication examples showing proper format
399 | - Explain all HTTP status codes and error handling
400 | - Cover complete request/response cycles
401 |
402 | ### Accessibility requirements
403 |
404 | - Include descriptive alt text for all images and diagrams
405 | - Use specific, actionable link text instead of "click here"
406 | - Ensure proper heading hierarchy starting with H2
407 | - Provide keyboard navigation considerations
408 | - Use sufficient color contrast in examples and visuals
409 | - Structure content for easy scanning with headers and lists
410 |
411 | ## Component selection logic
412 |
413 | - Use **Steps** for procedures and sequential instructions
414 | - Use **Tabs** for platform-specific content or alternative approaches
415 | - Use **CodeGroup** when showing the same concept in multiple programming languages
416 | - Use **Accordions** for progressive disclosure of information
417 | - Use **RequestExample/ResponseExample** specifically for API endpoint documentation
418 | - Use **ParamField** for API parameters, **ResponseField** for API responses
419 | - Use **Expandable** for nested object properties or hierarchical information
420 | ````
421 |
--------------------------------------------------------------------------------
/docs/ai-tools/windsurf.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Windsurf setup"
3 | description: "Configure Windsurf for your documentation workflow"
4 | icon: "water"
5 | ---
6 |
7 | Configure Windsurf's Cascade AI assistant to help you write and maintain documentation. This guide shows how to set up Windsurf specifically for your Mintlify documentation workflow.
8 |
9 | ## Prerequisites
10 |
11 | - Windsurf editor installed
12 | - Access to your documentation repository
13 |
14 | ## Workspace rules
15 |
16 | Create workspace rules that provide Windsurf with context about your documentation project and standards.
17 |
18 | Create `.windsurf/rules.md` in your project root:
19 |
20 | ````markdown
21 | # Mintlify technical writing rule
22 |
23 | ## Project context
24 |
25 | - This is a documentation project on the Mintlify platform
26 | - We use MDX files with YAML frontmatter
27 | - Navigation is configured in `docs.json`
28 | - We follow technical writing best practices
29 |
30 | ## Writing standards
31 |
32 | - Use second person ("you") for instructions
33 | - Write in active voice and present tense
34 | - Start procedures with prerequisites
35 | - Include expected outcomes for major steps
36 | - Use descriptive, keyword-rich headings
37 | - Keep sentences concise but informative
38 |
39 | ## Required page structure
40 |
41 | Every page must start with frontmatter:
42 |
43 | ```yaml
44 | ---
45 | title: "Clear, specific title"
46 | description: "Concise description for SEO and navigation"
47 | ---
48 | ```
49 |
50 | ## Mintlify components
51 |
52 | ### Callouts
53 |
54 | - `` for helpful supplementary information
55 | - `` for important cautions and breaking changes
56 | - `` for best practices and expert advice
57 | - `` for neutral contextual information
58 | - `` for success confirmations
59 |
60 | ### Code examples
61 |
62 | - When appropriate, include complete, runnable examples
63 | - Use `` for multiple language examples
64 | - Specify language tags on all code blocks
65 | - Include realistic data, not placeholders
66 | - Use `` and `` for API docs
67 |
68 | ### Procedures
69 |
70 | - Use `` component for sequential instructions
71 | - Include verification steps with `` components when relevant
72 | - Break complex procedures into smaller steps
73 |
74 | ### Content organization
75 |
76 | - Use `` for platform-specific content
77 | - Use `` for progressive disclosure
78 | - Use `` and `` for highlighting content
79 | - Wrap images in `` components with descriptive alt text
80 |
81 | ## API documentation requirements
82 |
83 | - Document all parameters with ``
84 | - Show response structure with ``
85 | - Include both success and error examples
86 | - Use `` for nested object properties
87 | - Always include authentication examples
88 |
89 | ## Quality standards
90 |
91 | - Test all code examples before publishing
92 | - Use relative paths for internal links
93 | - Include alt text for all images
94 | - Ensure proper heading hierarchy (start with h2)
95 | - Check existing patterns for consistency
96 | ````
97 |
--------------------------------------------------------------------------------
/docs/api/endpoints/exec.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Execute command"
3 | description: "Run a command inside a sandbox"
4 | ---
5 |
6 | Endpoint: `POST /api/v1/sandboxes/{name}/exec`
7 |
8 |
9 | ```bash cURL
10 | curl -X POST "$BASE/api/v1/sandboxes/my-sandbox/exec?namespace=default" \
11 | -H "X-API-Key: $K7_API_KEY" \
12 | -H "Content-Type: application/json" \
13 | -d '{"command": "echo Hello"}'
14 | ```
15 |
16 |
17 |
18 | ```json Success
19 | {
20 | "data": {
21 | "exit_code": 0,
22 | "stdout": "Hello\n",
23 | "stderr": "",
24 | "duration_ms": 12
25 | }
26 | }
27 | ```
28 |
29 |
30 | Sandbox name
31 | Namespace
32 | Shell command to execute
33 |
34 | ### Semantics
35 |
36 | - `exit_code`: `0` on success, non-zero when the command fails.
37 | - `stdout`/`stderr`: Raw streams captured from the process; may include newlines.
38 | - `duration_ms`: Client-observed duration including stream lifecycle.
39 |
40 | ### Examples
41 |
42 | ```bash
43 | curl -X POST "$BASE/api/v1/sandboxes/my-sandbox/exec?namespace=default" \
44 | -H "Authorization: Bearer $K7_API_KEY" \
45 | -H "Content-Type: application/json" \
46 | -d '{"command": "apk add --no-cache curl && curl -I https://example.com"}'
47 | ```
48 |
49 | Error example (non-zero exit):
50 |
51 | ```json
52 | {
53 | "data": {
54 | "exit_code": 2,
55 | "stdout": "",
56 | "stderr": "some error...",
57 | "duration_ms": 37
58 | }
59 | }
60 | ```
61 |
62 |
63 |
--------------------------------------------------------------------------------
/docs/api/endpoints/health.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Health"
3 | description: "Root and /health endpoints"
4 | ---
5 |
6 | ## Root
7 |
8 | Endpoint: `GET /`
9 |
10 | ```bash
11 | curl "$BASE/"
12 | ```
13 |
14 | Example:
15 |
16 | ```json
17 | { "message": "K7 Sandbox API", "version": "x.y.z" }
18 | ```
19 |
20 | ## Health
21 |
22 | Endpoint: `GET /health`
23 |
24 | ```bash
25 | curl "$BASE/health"
26 | ```
27 |
28 | Example:
29 |
30 | ```json
31 | { "status": "healthy" }
32 | ```
33 |
34 |
35 |
--------------------------------------------------------------------------------
/docs/api/endpoints/metrics.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Metrics"
3 | description: "Get CPU and memory usage for sandboxes"
4 | ---
5 |
6 | Endpoint: `GET /api/v1/sandboxes/metrics`
7 |
8 | Namespace
9 |
10 |
11 | ```bash cURL
12 | curl -H "X-API-Key: $K7_API_KEY" "$BASE/api/v1/sandboxes/metrics?namespace=default"
13 | ```
14 |
15 |
16 | Example response:
17 |
18 | ```json
19 | {
20 | "data": [
21 | { "name": "my-sandbox", "namespace": "default", "cpu_usage": "10m", "memory_usage": "64Mi" }
22 | ]
23 | }
24 | ```
25 |
26 | ### Units
27 |
28 | - `cpu_usage` uses Kubernetes format (e.g., `10m` = 10 millicores).
29 | - `memory_usage` uses Kubernetes format (e.g., `64Mi`).
30 |
31 |
32 |
--------------------------------------------------------------------------------
/docs/api/endpoints/sandboxes.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Sandboxes"
3 | description: "Create, list, get, and delete sandboxes"
4 | ---
5 |
6 | ## Create sandbox
7 |
8 | Endpoint: `POST /api/v1/sandboxes`
9 |
10 |
11 | ```bash cURL
12 | curl -X POST "$BASE/api/v1/sandboxes" \
13 | -H "X-API-Key: $K7_API_KEY" \
14 | -H "Content-Type: application/json" \
15 | -d '{
16 | "name": "my-sandbox",
17 | "image": "alpine:latest",
18 | "namespace": "default",
19 | "limits": {"cpu": "500m", "memory": "512Mi"}
20 | }'
21 | ```
22 |
23 |
24 | Body example:
25 |
26 | ```json
27 | {
28 | "name": "my-sandbox",
29 | "image": "alpine:latest",
30 | "namespace": "default",
31 | "limits": {"cpu": "500m", "memory": "512Mi"}
32 | }
33 | ```
34 |
35 | Body example with egress whitelist:
36 |
37 | ```json
38 | {
39 | "name": "my-restricted-sandbox",
40 | "image": "alpine:latest",
41 | "namespace": "default",
42 | "egress_whitelist": ["1.1.1.1/32", "8.8.8.8/32"],
43 | "limits": {"cpu": "500m", "memory": "512Mi"}
44 | }
45 | ```
46 |
47 |
48 | ```json Success
49 | {
50 | "data": {
51 | "name": "my-sandbox",
52 | "namespace": "default",
53 | "image": "alpine:latest"
54 | }
55 | }
56 | ```
57 |
58 |
59 | ### Request body schema
60 |
61 | Fields accepted in the JSON body when creating a sandbox:
62 |
63 | - `name` (string, required): Unique sandbox name in the namespace
64 | - `image` (string, required): Container image, e.g. `alpine:latest`
65 | - `namespace` (string, default `default`): Kubernetes namespace
66 | - `env_file` (string | null): Path (on API host) to `.env` file to inject as Secret
67 | - `before_script` (string, default empty): Shell commands to run before the container is marked Ready
68 | - `limits` (object): Resource limits/requests; keys supported: `cpu`, `memory`, `ephemeral-storage`
69 | - `egress_whitelist` (string[] | [] | null): See Egress section below
70 | - `pod_non_root` (boolean, default false): Run pod as non-root (UID/GID/FSGroup 65532)
71 | - `container_non_root` (boolean, default false): Run container as non-root (UID 65532)
72 | - `cap_drop` (string[] | null): List of capabilities to drop; default policy is `ALL`
73 | - `cap_add` (string[] | null): List of capabilities to add back
74 |
75 | ### Responses
76 |
77 | - `201 Created` with Location header to the created resource:
78 |
79 | ```json
80 | { "data": { "name": "my-sandbox", "namespace": "default", "image": "alpine:latest" } }
81 | ```
82 |
83 | - `400 BadRequest` when validation fails (invalid limits, bad env file, already exists, etc.)
84 |
85 |
86 | ## List sandboxes
87 |
88 | Endpoint: `GET /api/v1/sandboxes`
89 |
90 | Namespace
91 |
92 |
93 | ```bash cURL
94 | curl -H "X-API-Key: $K7_API_KEY" "$BASE/api/v1/sandboxes?namespace=default"
95 | ```
96 |
97 |
98 | Returns list of sandbox objects with fields: name, namespace, status, ready, restarts, age, image, error_message.
99 |
100 |
101 | ```json Success
102 | {
103 | "data": [
104 | {
105 | "name": "my-sandbox",
106 | "namespace": "default",
107 | "status": "Running",
108 | "ready": "True",
109 | "restarts": 0,
110 | "age": "0:05:42",
111 | "image": "alpine:latest",
112 | "error_message": ""
113 | }
114 | ]
115 | }
116 | ```
117 |
118 |
119 | ## Get sandbox
120 |
121 | Endpoint: `GET /api/v1/sandboxes/{name}`
122 |
123 | Sandbox name
124 | Namespace
125 |
126 |
127 | ```bash cURL
128 | curl -H "X-API-Key: $K7_API_KEY" "$BASE/api/v1/sandboxes/my-sandbox?namespace=default"
129 | ```
130 |
131 |
132 |
133 | ```json Success
134 | {
135 | "data": {
136 | "name": "my-sandbox",
137 | "namespace": "default",
138 | "status": "Running",
139 | "ready": "True",
140 | "restarts": 0,
141 | "age": "0:05:42",
142 | "image": "alpine:latest",
143 | "error_message": ""
144 | }
145 | }
146 | ```
147 |
148 |
149 | ## Delete sandbox
150 |
151 | Endpoint: `DELETE /api/v1/sandboxes/{name}`
152 |
153 | Sandbox name
154 | Namespace
155 |
156 |
157 | ```bash cURL
158 | curl -X DELETE -H "X-API-Key: $K7_API_KEY" \
159 | "$BASE/api/v1/sandboxes/my-sandbox?namespace=default"
160 | ```
161 |
162 |
163 |
164 | ```json Success
165 | { "data": { "message": "Sandbox my-sandbox deleted successfully" } }
166 | ```
167 |
168 |
169 | ## Delete all sandboxes
170 |
171 | Endpoint: `DELETE /api/v1/sandboxes`
172 |
173 | Namespace
174 |
175 |
176 | ```bash cURL
177 | curl -X DELETE -H "X-API-Key: $K7_API_KEY" \
178 | "$BASE/api/v1/sandboxes?namespace=default"
179 | ```
180 |
181 |
182 |
183 | ```json Success
184 | {
185 | "data": {
186 | "message": "Deleted 1 sandboxes",
187 | "results": [ { "name": "my-sandbox", "success": true, "error": null } ]
188 | }
189 | }
190 | ```
191 |
192 |
193 |
194 | Deleting sandboxes is irreversible.
195 |
196 |
197 | ## See also
198 |
199 | - API Security & networking: `/api/security`
200 |
201 |
202 |
--------------------------------------------------------------------------------
/docs/api/introduction.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Auth & responses"
3 | description: "Authentication, base URL, and response format"
4 | ---
5 |
6 | Base URL: `https://` (see `k7 api-status` / `k7 get-api-endpoint`).
7 |
8 | ## Authentication
9 |
10 | Send your API key via either header:
11 |
12 | ```http
13 | X-API-Key:
14 | # or
15 | Authorization: Bearer
16 | ```
17 |
18 | All endpoints return standard HTTP codes. `401 Unauthorized` if the key is missing/invalid/expired.
19 |
20 | ## Response envelope
21 |
22 | Successful responses:
23 |
24 | ```json
25 | { "data": ... }
26 | ```
27 |
28 | Errors:
29 |
30 | ```json
31 | { "error": { "code": "BadRequest", "message": "..." } }
32 | ```
33 |
34 | Common error codes:
35 |
36 | - `BadRequest` (400): Invalid input or missing parameters
37 | - `Unauthorized` (401): Missing or invalid API key
38 | - `NotFound` (404): Resource was not found
39 | - `Conflict` (409): Resource already exists
40 | - `UnprocessableEntity` (422): Validation failed
41 | - `InternalServerError` (500): Unhandled error
42 |
43 | ## Headers
44 |
45 | Required headers for requests with body:
46 |
47 | ```http
48 | Content-Type: application/json
49 | ```
50 |
51 | Authentication headers (either):
52 |
53 | ```http
54 | X-API-Key:
55 | # or
56 | Authorization: Bearer
57 | ```
58 |
59 | ## Resources
60 |
61 | - Sandboxes: create, list, get, delete, delete-all
62 | - Exec: run a command in a sandbox and get stdout/stderr/exit_code
63 | - Metrics: CPU and memory usage per sandbox
64 |
65 |
66 | Health endpoints:
67 |
68 | - `GET /` → basic API info
69 | - `GET /health` → health check
70 |
71 |
72 |
73 |
--------------------------------------------------------------------------------
/docs/api/security.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Security & networking"
3 | description: "Non-root execution, Linux capabilities, and egress control"
4 | ---
5 |
6 | This page covers sandbox security posture and how to configure it via the API.
7 |
8 | ## Non-root execution
9 |
10 | - `pod_non_root` (boolean, default false): Run the Pod as non-root (UID/GID/FSGroup 65532). Applies pod-wide filesystem ownership.
11 | - `container_non_root` (boolean, default false): Run the main container as non-root (UID 65532) and disallow privilege escalation.
12 |
13 | Guidance:
14 | - Enable both flags for consistent non-root behavior and fewer permission surprises when writing to volumes.
15 | - Some package managers (e.g., Alpine `apk add`) require root. To run `apk add` inside the container, you have options:
16 | - Use `before_script` with a base image that already includes needed tools, or
17 | - Temporarily run the main container with root by leaving `container_non_root` disabled for setup, or
18 | - Build a custom image with dependencies pre-installed (recommended for production reproducibility).
19 |
20 | Example (non-root):
21 |
22 | ```json
23 | {
24 | "name": "nr-example",
25 | "image": "alpine:latest",
26 | "pod_non_root": true,
27 | "container_non_root": true
28 | }
29 | ```
30 |
31 | Example (install packages first as root, then lock down egress):
32 |
33 | ```json
34 | {
35 | "name": "setup-then-lock",
36 | "image": "alpine:latest",
37 | "before_script": "apk add --no-cache curl git",
38 | "egress_whitelist": ["203.0.113.0/24"]
39 | }
40 | ```
41 |
42 | ## Linux capabilities
43 |
44 | Default policy: drop ALL capabilities. Add back only what you need. If you specify `cap_drop` explicitly, you override the default; to keep `drop ALL` and add back minimal caps, leave `cap_drop` unset and only use `cap_add`.
45 |
46 | - `cap_drop` (string[]): Capabilities to drop. If omitted, `ALL` is dropped by default.
47 | - `cap_add` (string[]): Capabilities to add back.
48 | - `allow_privilege_escalation`: always set to `false`.
49 | - Seccomp profile: `RuntimeDefault`.
50 |
51 | Examples:
52 |
53 | Minimal add-back while still dropping ALL by default:
54 |
55 | ```json
56 | {
57 | "name": "caps-minimal",
58 | "image": "alpine:latest",
59 | "cap_add": ["CHOWN"],
60 | "cap_drop": null
61 | }
62 | ```
63 |
64 | Override drop policy (not recommended unless you know why):
65 |
66 | ```json
67 | {
68 | "name": "caps-custom",
69 | "image": "alpine:latest",
70 | "cap_drop": ["NET_RAW"],
71 | "cap_add": []
72 | }
73 | ```
74 |
75 | ## Network isolation and egress lockdown
76 |
77 | ### Ingress isolation (Default: Enabled)
78 |
79 | **All inter-VM communication is blocked by default** to prevent sandbox-to-sandbox access. This provides strong isolation between different sandboxes running in the same cluster.
80 |
81 | **Key points:**
82 | - **Ingress blocking**: VM sandboxes cannot communicate with each other by default
83 | - **Administrative access preserved**: `kubectl exec` and `k7 shell` still work normally (they use the Kubernetes API, not pod networking)
84 | - **System services allowed**: Traffic from `kube-system` namespace is permitted for cluster functionality
85 | - **No configuration needed**: This security feature is enabled by default for all sandboxes
86 |
87 | ### Egress lockdown and whitelisting
88 |
89 | Use `egress_whitelist` to control outbound traffic. The policy is applied after the container becomes Ready so `before_script` runs with open egress.
90 |
91 | Behavior:
92 | - Omit `egress_whitelist`: egress open (external internet allowed).
93 | - `[]`: full egress block (DNS to CoreDNS allowed on TCP/UDP 53).
94 | - `["CIDR", ...]`: allow only listed CIDR blocks (+ DNS to CoreDNS).
95 |
96 | Examples:
97 |
98 | Full isolation (no inter-VM communication, no external access):
99 | ```json
100 | { "name": "fully-isolated", "image": "alpine:latest", "egress_whitelist": [] }
101 | ```
102 |
103 | Partial isolation (no inter-VM communication, but external internet allowed):
104 | ```json
105 | { "name": "partial-isolation", "image": "alpine:latest" }
106 | ```
107 |
108 | Whitelist specific external services:
109 | ```json
110 | {
111 | "name": "egress-restricted",
112 | "image": "alpine:latest",
113 | "egress_whitelist": ["1.1.1.1/32", "8.8.8.8/32"]
114 | }
115 | ```
116 |
117 |
118 | **Network Policy Details:**
119 | - **Ingress**: Blocked by default (inter-VM isolation) - system services and kubectl exec still work
120 | - **DNS allowance**: When locking down egress, DNS to CoreDNS inside the cluster is always allowed
121 | - **Administrative access**: `kubectl exec`, `k7 shell`, and API operations bypass network policies
122 |
123 |
124 |
125 |
--------------------------------------------------------------------------------
/docs/development.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Development'
3 | description: 'Preview changes locally to update your docs'
4 | ---
5 |
6 |
7 | **Prerequisites**:
8 | - Node.js version 19 or higher
9 | - A docs repository with a `docs.json` file
10 |
11 |
12 | Follow these steps to install and run Mintlify on your operating system.
13 |
14 |
15 |
16 |
17 | ```bash
18 | npm i -g mint
19 | ```
20 |
21 |
22 |
23 |
24 | Navigate to your docs directory where your `docs.json` file is located, and run the following command:
25 |
26 | ```bash
27 | mint dev
28 | ```
29 |
30 | A local preview of your documentation will be available at `http://localhost:3000`.
31 |
32 |
33 |
34 |
35 | ## Custom ports
36 |
37 | By default, Mintlify uses port 3000. You can customize the port Mintlify runs on by using the `--port` flag. For example, to run Mintlify on port 3333, use this command:
38 |
39 | ```bash
40 | mint dev --port 3333
41 | ```
42 |
43 | If you attempt to run Mintlify on a port that's already in use, it will use the next available port:
44 |
45 | ```md
46 | Port 3000 is already in use. Trying 3001 instead.
47 | ```
48 |
49 | ## Mintlify versions
50 |
51 | Please note that each CLI release is associated with a specific version of Mintlify. If your local preview does not align with the production version, please update the CLI:
52 |
53 | ```bash
54 | npm mint update
55 | ```
56 |
57 | ## Validating links
58 |
59 | The CLI can assist with validating links in your documentation. To identify any broken links, use the following command:
60 |
61 | ```bash
62 | mint broken-links
63 | ```
64 |
65 | ## Deployment
66 |
67 | If the deployment is successful, you should see the following:
68 |
69 |
70 | 
71 |
72 |
73 | ## Code formatting
74 |
75 | We suggest using extensions on your IDE to recognize and format MDX. If you're a VSCode user, consider the [MDX VSCode extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) for syntax highlighting, and [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) for code formatting.
76 |
77 | ## Troubleshooting
78 |
79 |
80 |
81 |
82 | This may be due to an outdated version of node. Try the following:
83 | 1. Remove the currently-installed version of the CLI: `npm remove -g mint`
84 | 2. Upgrade to Node v19 or higher.
85 | 3. Reinstall the CLI: `npm i -g mint`
86 |
87 |
88 |
89 |
90 | Solution: Go to the root of your device and delete the `~/.mintlify` folder. Then run `mint dev` again.
91 |
92 |
93 |
94 | Curious about what changed in the latest CLI version? Check out the [CLI changelog](https://www.npmjs.com/package/mintlify?activeTab=versions).
95 |
--------------------------------------------------------------------------------
/docs/docs.json:
--------------------------------------------------------------------------------
1 | {
2 | "$schema": "https://mintlify.com/docs.json",
3 | "theme": "linden",
4 | "name": "Docs",
5 | "colors": {
6 | "primary": "#ef672b",
7 | "light": "#ef672b",
8 | "dark": "#ef672b"
9 | },
10 | "appearance": {
11 | "default": "dark",
12 | "background": {
13 | "color": { "dark": "#000000" }
14 | }
15 | },
16 | "favicon": "/favicon.png",
17 | "navigation": {
18 | "tabs": [
19 | {
20 | "tab": "Docs",
21 | "groups": [
22 | {
23 | "group": "Getting started",
24 | "pages": [
25 | "index",
26 | "getting-started/installation"
27 | ]
28 | },
29 | {
30 | "group": "Using Katakate",
31 | "pages": [
32 | "guides/cli",
33 | "guides/python-sdk",
34 | "guides/langchain-agent",
35 | "guides/utilities"
36 | ]
37 | },
38 | {
39 | "group": "API overview",
40 | "pages": [
41 | "api/introduction",
42 | "api/security"
43 | ]
44 | },
45 | {
46 | "group": "API endpoints",
47 | "pages": [
48 | "api/endpoints/sandboxes",
49 | "api/endpoints/exec",
50 | "api/endpoints/metrics",
51 | "api/endpoints/health"
52 | ]
53 | }
54 | ]
55 | }
56 | ]
57 | },
58 | "logo": {
59 | "light": "/images/k7-logo.png",
60 | "dark": "/images/k7-logo.png"
61 | },
62 | "navbar": {
63 | "links": [
64 | {
65 | "label": "GitHub",
66 | "href": "https://github.com/Katakate/k7"
67 | }
68 | ]
69 | },
70 | "contextual": {
71 | "options": [
72 | "copy",
73 | "view",
74 | "chatgpt",
75 | "claude",
76 | "perplexity",
77 | "mcp",
78 | "cursor",
79 | "vscode"
80 | ]
81 | },
82 | "footer": {
83 | "socials": {
84 | "github": "https://github.com/Katakate"
85 | }
86 | }
87 | }
--------------------------------------------------------------------------------
/docs/essentials/code.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Code blocks'
3 | description: 'Display inline code and code blocks'
4 | icon: 'code'
5 | ---
6 |
7 | ## Inline code
8 |
9 | To denote a `word` or `phrase` as code, enclose it in backticks (`).
10 |
11 | ```
12 | To denote a `word` or `phrase` as code, enclose it in backticks (`).
13 | ```
14 |
15 | ## Code blocks
16 |
17 | Use [fenced code blocks](https://www.markdownguide.org/extended-syntax/#fenced-code-blocks) by enclosing code in three backticks and follow the leading ticks with the programming language of your snippet to get syntax highlighting. Optionally, you can also write the name of your code after the programming language.
18 |
19 | ```java HelloWorld.java
20 | class HelloWorld {
21 | public static void main(String[] args) {
22 | System.out.println("Hello, World!");
23 | }
24 | }
25 | ```
26 |
27 | ````md
28 | ```java HelloWorld.java
29 | class HelloWorld {
30 | public static void main(String[] args) {
31 | System.out.println("Hello, World!");
32 | }
33 | }
34 | ```
35 | ````
36 |
--------------------------------------------------------------------------------
/docs/essentials/images.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Images and embeds'
3 | description: 'Add image, video, and other HTML elements'
4 | icon: 'image'
5 | ---
6 |
7 | 
11 |
12 | ## Image
13 |
14 | ### Using Markdown
15 |
16 | The [markdown syntax](https://www.markdownguide.org/basic-syntax/#images) lets you add images using the following code
17 |
18 | ```md
19 | 
20 | ```
21 |
22 | Note that the image file size must be less than 5MB. Otherwise, we recommend hosting on a service like [Cloudinary](https://cloudinary.com/) or [S3](https://aws.amazon.com/s3/). You can then use that URL and embed.
23 |
24 | ### Using embeds
25 |
26 | To get more customizability with images, you can also use [embeds](/writing-content/embed) to add images
27 |
28 | ```html
29 | 
30 | ```
31 |
32 | ## Embeds and HTML elements
33 |
34 |
44 |
45 |
46 |
47 |
48 |
49 | Mintlify supports [HTML tags in Markdown](https://www.markdownguide.org/basic-syntax/#html). This is helpful if you prefer HTML tags to Markdown syntax, and lets you create documentation with infinite flexibility.
50 |
51 |
52 |
53 | ### iFrames
54 |
55 | Loads another HTML page within the document. Most commonly used for embedding videos.
56 |
57 | ```html
58 |
59 | ```
60 |
--------------------------------------------------------------------------------
/docs/essentials/markdown.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Markdown syntax'
3 | description: 'Text, title, and styling in standard markdown'
4 | icon: 'text-size'
5 | ---
6 |
7 | ## Titles
8 |
9 | Best used for section headers.
10 |
11 | ```md
12 | ## Titles
13 | ```
14 |
15 | ### Subtitles
16 |
17 | Best used for subsection headers.
18 |
19 | ```md
20 | ### Subtitles
21 | ```
22 |
23 |
24 |
25 | Each **title** and **subtitle** creates an anchor and also shows up on the table of contents on the right.
26 |
27 |
28 |
29 | ## Text formatting
30 |
31 | We support most markdown formatting. Simply add `**`, `_`, or `~` around text to format it.
32 |
33 | | Style | How to write it | Result |
34 | | ------------- | ----------------- | --------------- |
35 | | Bold | `**bold**` | **bold** |
36 | | Italic | `_italic_` | _italic_ |
37 | | Strikethrough | `~strikethrough~` | ~strikethrough~ |
38 |
39 | You can combine these. For example, write `**_bold and italic_**` to get **_bold and italic_** text.
40 |
41 | You need to use HTML to write superscript and subscript text. That is, add `` or `` around your text.
42 |
43 | | Text Size | How to write it | Result |
44 | | ----------- | ------------------------ | ---------------------- |
45 | | Superscript | `superscript` | superscript |
46 | | Subscript | `subscript` | subscript |
47 |
48 | ## Linking to pages
49 |
50 | You can add a link by wrapping text in `[]()`. You would write `[link to google](https://google.com)` to [link to google](https://google.com).
51 |
52 | Links to pages in your docs need to be root-relative. Basically, you should include the entire folder path. For example, `[link to text](/writing-content/text)` links to the page "Text" in our components section.
53 |
54 | Relative links like `[link to text](../text)` will open slower because we cannot optimize them as easily.
55 |
56 | ## Blockquotes
57 |
58 | ### Singleline
59 |
60 | To create a blockquote, add a `>` in front of a paragraph.
61 |
62 | > Dorothy followed her through many of the beautiful rooms in her castle.
63 |
64 | ```md
65 | > Dorothy followed her through many of the beautiful rooms in her castle.
66 | ```
67 |
68 | ### Multiline
69 |
70 | > Dorothy followed her through many of the beautiful rooms in her castle.
71 | >
72 | > The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
73 |
74 | ```md
75 | > Dorothy followed her through many of the beautiful rooms in her castle.
76 | >
77 | > The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
78 | ```
79 |
80 | ### LaTeX
81 |
82 | Mintlify supports [LaTeX](https://www.latex-project.org) through the Latex component.
83 |
84 | 8 x (vk x H1 - H2) = (0,1)
85 |
86 | ```md
87 | 8 x (vk x H1 - H2) = (0,1)
88 | ```
89 |
--------------------------------------------------------------------------------
/docs/essentials/navigation.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Navigation'
3 | description: 'The navigation field in docs.json defines the pages that go in the navigation menu'
4 | icon: 'map'
5 | ---
6 |
7 | The navigation menu is the list of links on every website.
8 |
9 | You will likely update `docs.json` every time you add a new page. Pages do not show up automatically.
10 |
11 | ## Navigation syntax
12 |
13 | Our navigation syntax is recursive which means you can make nested navigation groups. You don't need to include `.mdx` in page names.
14 |
15 |
16 |
17 | ```json Regular Navigation
18 | "navigation": {
19 | "tabs": [
20 | {
21 | "tab": "Docs",
22 | "groups": [
23 | {
24 | "group": "Getting Started",
25 | "pages": ["quickstart"]
26 | }
27 | ]
28 | }
29 | ]
30 | }
31 | ```
32 |
33 | ```json Nested Navigation
34 | "navigation": {
35 | "tabs": [
36 | {
37 | "tab": "Docs",
38 | "groups": [
39 | {
40 | "group": "Getting Started",
41 | "pages": [
42 | "quickstart",
43 | {
44 | "group": "Nested Reference Pages",
45 | "pages": ["nested-reference-page"]
46 | }
47 | ]
48 | }
49 | ]
50 | }
51 | ]
52 | }
53 | ```
54 |
55 |
56 |
57 | ## Folders
58 |
59 | Simply put your MDX files in folders and update the paths in `docs.json`.
60 |
61 | For example, to have a page at `https://yoursite.com/your-folder/your-page` you would make a folder called `your-folder` containing an MDX file called `your-page.mdx`.
62 |
63 |
64 |
65 | You cannot use `api` for the name of a folder unless you nest it inside another folder. Mintlify uses Next.js which reserves the top-level `api` folder for internal server calls. A folder name such as `api-reference` would be accepted.
66 |
67 |
68 |
69 | ```json Navigation With Folder
70 | "navigation": {
71 | "tabs": [
72 | {
73 | "tab": "Docs",
74 | "groups": [
75 | {
76 | "group": "Group Name",
77 | "pages": ["your-folder/your-page"]
78 | }
79 | ]
80 | }
81 | ]
82 | }
83 | ```
84 |
85 | ## Hidden pages
86 |
87 | MDX files not included in `docs.json` will not show up in the sidebar but are accessible through the search bar and by linking directly to them.
88 |
--------------------------------------------------------------------------------
/docs/essentials/reusable-snippets.mdx:
--------------------------------------------------------------------------------
1 | ---
2 | title: "Reusable snippets"
3 | description: "Reusable, custom snippets to keep content in sync"
4 | icon: "recycle"
5 | ---
6 |
7 | import SnippetIntro from '/snippets/snippet-intro.mdx';
8 |
9 |
10 |
11 | ## Creating a custom snippet
12 |
13 | **Pre-condition**: You must create your snippet file in the `snippets` directory.
14 |
15 |
16 | Any page in the `snippets` directory will be treated as a snippet and will not
17 | be rendered into a standalone page. If you want to create a standalone page
18 | from the snippet, import the snippet into another file and call it as a
19 | component.
20 |
21 |
22 | ### Default export
23 |
24 | 1. Add content to your snippet file that you want to re-use across multiple
25 | locations. Optionally, you can add variables that can be filled in via props
26 | when you import the snippet.
27 |
28 | ```mdx snippets/my-snippet.mdx
29 | Hello world! This is my content I want to reuse across pages. My keyword of the
30 | day is {word}.
31 | ```
32 |
33 |
34 | The content that you want to reuse must be inside the `snippets` directory in
35 | order for the import to work.
36 |
37 |
38 | 2. Import the snippet into your destination file.
39 |
40 | ```mdx destination-file.mdx
41 | ---
42 | title: My title
43 | description: My Description
44 | ---
45 |
46 | import MySnippet from '/snippets/path/to/my-snippet.mdx';
47 |
48 | ## Header
49 |
50 | Lorem impsum dolor sit amet.
51 |
52 |
53 | ```
54 |
55 | ### Reusable variables
56 |
57 | 1. Export a variable from your snippet file:
58 |
59 | ```mdx snippets/path/to/custom-variables.mdx
60 | export const myName = 'my name';
61 |
62 | export const myObject = { fruit: 'strawberries' };
63 | ```
64 |
65 | 2. Import the snippet from your destination file and use the variable:
66 |
67 | ```mdx destination-file.mdx
68 | ---
69 | title: My title
70 | description: My Description
71 | ---
72 |
73 | import { myName, myObject } from '/snippets/path/to/custom-variables.mdx';
74 |
75 | Hello, my name is {myName} and I like {myObject.fruit}.
76 | ```
77 |
78 | ### Reusable components
79 |
80 | 1. Inside your snippet file, create a component that takes in props by exporting
81 | your component in the form of an arrow function.
82 |
83 | ```mdx snippets/custom-component.mdx
84 | export const MyComponent = ({ title }) => (
85 |
86 |
{title}
87 |
... snippet content ...
88 |
8 |
9 |
10 | Katakate (k7) gives you production-grade, isolated sandboxes backed by Kata Containers and Firecracker, orchestrated with Kubernetes. Use the `k7` CLI to provision sandboxes, the REST API to manage them remotely, and the Python SDK to integrate into apps and agents.
11 |
12 |
13 |
14 | Get running in minutes: install, start API, create your first sandbox.
15 |
16 |
17 | All `k7` commands with examples.
18 |
19 |
20 | Sync and async clients with complete examples.
21 |
22 |
23 | Endpoint overview, request/response formats, and errors.
24 |
25 |
26 | Build a ReAct agent that executes inside a sandbox.
27 |
28 |
29 |
--------------------------------------------------------------------------------
/docs/snippets/snippet-intro.mdx:
--------------------------------------------------------------------------------
1 | One of the core principles of software development is DRY (Don't Repeat
2 | Yourself). This is a principle that applies to documentation as
3 | well. If you find yourself repeating the same content in multiple places, you
4 | should consider creating a custom snippet to keep your content in sync.
5 |
--------------------------------------------------------------------------------
/docs/tutorials/k7_hetzner_node_setup.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Katakate/k7/f48ae38b9aeeec52e50aad8f157451b10e5ffc65/docs/tutorials/k7_hetzner_node_setup.pdf
--------------------------------------------------------------------------------
/examples/k7.yaml:
--------------------------------------------------------------------------------
1 | name: demo
2 | image: alpine:3.20
3 | namespace: default
4 | limits:
5 | cpu: "100m"
6 | memory: "128Mi"
7 | before_script: |
8 | # Installing curl. Egress open during before_script, then restricted (empty whitelist) afterwards
9 | apk add curl
10 | egress_whitelist: []
11 |
--------------------------------------------------------------------------------
/setup.py:
--------------------------------------------------------------------------------
1 | from setuptools import setup, find_packages
2 |
3 | setup(
4 | name="katakate",
5 | version="0.0.4-dev",
6 | description="Katakate Sandbox Management Python SDK",
7 | packages=find_packages(where="src", include=["katakate", "katakate.*"]),
8 | package_dir={"": "src"},
9 | include_package_data=True,
10 | install_requires=[
11 | "requests>=2.31.0",
12 | ],
13 | extras_require={
14 | "sdk-async": ["httpx>=0.27.0"],
15 | },
16 | python_requires=">=3.8",
17 | )
18 |
--------------------------------------------------------------------------------
/src/README.md:
--------------------------------------------------------------------------------
1 | - `k7` is the .deb package containing the CLI and API, aimed to be used on the node(s), installable with `apt get`.
2 | - `katakate` is the PyPI package containing the Python SDK, aimed to be used remotely e.g. from local, installable with `pip install katakate`. The SDK client talks to the API deployed on the node.
--------------------------------------------------------------------------------
/src/k7/README.md:
--------------------------------------------------------------------------------
1 | Both the API in `api/` and the CLI in `cli/` use the shared core logic in `core/`. The node installation and configuration is handled by the Ansible playbook in `deploy/` and this is what is used when running `k7 install`.
--------------------------------------------------------------------------------
/src/k7/__init__.py:
--------------------------------------------------------------------------------
1 | """K7 Sandbox Management System"""
2 |
3 | __version__ = "0.0.4-dev"
4 |
--------------------------------------------------------------------------------
/src/k7/api/Dockerfile.api:
--------------------------------------------------------------------------------
1 | FROM ghcr.io/astral-sh/uv:python3.12-bookworm AS build
2 | WORKDIR /app
3 |
4 | # Copy requirements and full k7 package from repo-root context (src/ layout)
5 | COPY src/k7/api/requirements.txt ./requirements.txt
6 | COPY src/k7/ ./k7/
7 |
8 | RUN uv venv /app/.venv && \
9 | . /app/.venv/bin/activate && \
10 | uv pip install --no-cache -r requirements.txt
11 |
12 | FROM python:3.12-slim AS runtime
13 | ENV VIRTUAL_ENV=/app/.venv
14 | ENV PATH="/app/.venv/bin:$PATH"
15 | ENV PYTHONPATH="/app"
16 | WORKDIR /app
17 |
18 | RUN apt-get update && apt-get install -y --no-install-recommends \
19 | ca-certificates \
20 | && rm -rf /var/lib/apt/lists/*
21 |
22 | COPY --from=build /app/.venv /app/.venv
23 | COPY --from=build /app/k7 /app/k7
24 |
25 | RUN useradd -m -u 1000 k7user && chown -R k7user:k7user /app
26 | USER k7user
27 |
28 | EXPOSE 8000
29 | CMD ["uvicorn", "k7.api.main:app", "--host", "0.0.0.0", "--port", "8000"]
30 |
--------------------------------------------------------------------------------
/src/k7/api/__init__.py:
--------------------------------------------------------------------------------
1 | """K7 FastAPI Application"""
2 |
--------------------------------------------------------------------------------
/src/k7/api/docker-compose.yml:
--------------------------------------------------------------------------------
1 | services:
2 | cloudflared:
3 | image: cloudflare/cloudflared:latest
4 | container_name: k7-cloudflared
5 | restart: unless-stopped
6 | command: tunnel --no-autoupdate --url http://k7-api:8000
7 | depends_on:
8 | k7-api:
9 | condition: service_healthy
10 | networks:
11 | - k7-network
12 |
13 | k7-api:
14 | image: ${K7_API_IMAGE:-ghcr.io/katakate/k7-api}:${K7_API_TAG:-latest}
15 | pull_policy: if_not_present
16 | container_name: k7-api
17 | restart: unless-stopped
18 | user: "0:0"
19 | volumes:
20 | - /etc/rancher/k3s/k3s.yaml:/etc/rancher/k3s/k3s.yaml:ro
21 | - /etc/k7:/etc/k7
22 | environment:
23 | - KUBECONFIG=/etc/rancher/k3s/k3s.yaml
24 | - K7_API_KEYS_FILE=/etc/k7/api_keys.json
25 | healthcheck:
26 | test: ["CMD-SHELL", "python -c 'import sys,urllib.request; sys.exit(0) if urllib.request.urlopen(\"http://127.0.0.1:8000/health\", timeout=2).status==200 else sys.exit(1)' "]
27 | interval: 5s
28 | timeout: 3s
29 | retries: 10
30 | start_period: 10s
31 | networks:
32 | - k7-network
33 |
34 | networks:
35 | k7-network:
36 | driver: bridge
--------------------------------------------------------------------------------
/src/k7/api/main.py:
--------------------------------------------------------------------------------
1 | from fastapi import FastAPI, HTTPException, Depends, Header, status, Request
2 | from fastapi.responses import JSONResponse
3 | from typing import Optional, Any, Dict
4 | import os
5 | import json
6 | import hashlib
7 | import secrets
8 | import time
9 | from pathlib import Path
10 |
11 | from ..core.core import K7Core
12 | from ..core.models import SandboxConfig
13 | from .. import __version__
14 |
15 | app = FastAPI(title="K7 Sandbox API", version=__version__)
16 |
17 | API_KEYS_FILE = Path(os.getenv("K7_API_KEYS_FILE", "/etc/k7/api_keys.json"))
18 |
19 |
20 | def load_api_keys() -> dict:
21 | """Load API keys from file."""
22 | if not API_KEYS_FILE.exists():
23 | return {}
24 | try:
25 | with open(API_KEYS_FILE, "r") as f:
26 | data = json.load(f)
27 | except Exception:
28 | return {}
29 | # Purge expired keys opportunistically
30 | now_ts = int(time.time())
31 | changed = False
32 | for h, v in list(data.items()):
33 | exp = v.get("expires")
34 | if isinstance(exp, int) and now_ts > exp:
35 | del data[h]
36 | changed = True
37 | if changed:
38 | save_api_keys(data)
39 | return data
40 |
41 |
42 | def save_api_keys(keys: dict):
43 | """Save API keys to file with proper permissions."""
44 | API_KEYS_FILE.parent.mkdir(parents=True, exist_ok=True)
45 | with open(API_KEYS_FILE, "w") as f:
46 | json.dump(keys, f, indent=2)
47 | os.chmod(API_KEYS_FILE, 0o600)
48 |
49 |
50 | async def verify_api_key(
51 | x_api_key: Optional[str] = Header(None),
52 | authorization: Optional[str] = Header(None),
53 | ):
54 | """Verify API key via X-API-Key or Authorization: Bearer header.
55 |
56 | Uses timing-attack-resistant comparison and updates last_used on success.
57 | """
58 | token: Optional[str] = None
59 | if x_api_key and x_api_key.strip():
60 | token = x_api_key.strip()
61 | elif authorization and authorization.lower().startswith("bearer "):
62 | token = authorization[7:].strip()
63 |
64 | if not token:
65 | raise HTTPException(status_code=401, detail="Missing API key")
66 |
67 | api_keys = load_api_keys()
68 | key_hash = hashlib.sha256(token.encode()).hexdigest()
69 |
70 | valid_hash = None
71 | valid_data = None
72 | for stored_hash, key_data in api_keys.items():
73 | if secrets.compare_digest(key_hash, stored_hash):
74 | valid_hash = stored_hash
75 | valid_data = key_data
76 | break
77 |
78 | if valid_data is None:
79 | raise HTTPException(status_code=401, detail="Invalid API key")
80 |
81 | # Enforce expiry if present
82 | now_ts = int(time.time())
83 | expires_ts = valid_data.get("expires")
84 | if isinstance(expires_ts, int) and now_ts > expires_ts:
85 | raise HTTPException(status_code=401, detail="API key expired")
86 |
87 | api_keys[valid_hash]["last_used"] = now_ts
88 | save_api_keys(api_keys)
89 |
90 | return valid_data
91 |
92 |
93 | def success_response(data: Any, status_code: int = status.HTTP_200_OK, headers: Dict[str, str] | None = None) -> JSONResponse:
94 | return JSONResponse(content={"data": data}, status_code=status_code, headers=headers)
95 |
96 |
97 | def error_response(code: str, message: str, status_code: int) -> JSONResponse:
98 | return JSONResponse(content={"error": {"code": code, "message": message}}, status_code=status_code)
99 |
100 |
101 | @app.exception_handler(HTTPException)
102 | async def http_exception_handler(request: Request, exc: HTTPException): # type: ignore[override]
103 | # Map common status codes to generic error codes
104 | code_map = {
105 | 400: "BadRequest",
106 | 401: "Unauthorized",
107 | 403: "Forbidden",
108 | 404: "NotFound",
109 | 409: "Conflict",
110 | 422: "UnprocessableEntity",
111 | 500: "InternalServerError",
112 | }
113 | code = code_map.get(exc.status_code, "Error")
114 | # FastAPI often sets detail to str or dict; normalize to str
115 | detail = exc.detail if isinstance(exc.detail, str) else str(exc.detail)
116 | return error_response(code, detail, exc.status_code)
117 |
118 |
119 | @app.exception_handler(Exception)
120 | async def unhandled_exception_handler(request: Request, exc: Exception): # type: ignore[override]
121 | return error_response("InternalServerError", str(exc), status.HTTP_500_INTERNAL_SERVER_ERROR)
122 |
123 |
124 | @app.get("/")
125 | async def root():
126 | """Root endpoint."""
127 | return {"message": "K7 Sandbox API", "version": __version__}
128 |
129 |
130 | @app.get("/health")
131 | async def health():
132 | """Health check endpoint."""
133 | return {"status": "healthy"}
134 |
135 |
136 | @app.post("/api/v1/sandboxes", dependencies=[Depends(verify_api_key)])
137 | async def create_sandbox(config: dict):
138 | """Create a new sandbox."""
139 | try:
140 | sandbox_config = SandboxConfig.from_dict(config)
141 | core = K7Core()
142 | result = core.create_sandbox(sandbox_config)
143 |
144 | if result.success:
145 | resource = {
146 | "name": sandbox_config.name,
147 | "namespace": sandbox_config.namespace,
148 | "image": sandbox_config.image,
149 | }
150 | location = f"/api/v1/sandboxes/{sandbox_config.name}?namespace={sandbox_config.namespace}"
151 | return success_response(resource, status_code=status.HTTP_201_CREATED, headers={"Location": location})
152 | else:
153 | raise HTTPException(status_code=400, detail=result.error)
154 | except Exception as e:
155 | raise HTTPException(status_code=400, detail=str(e))
156 |
157 |
158 | @app.get("/api/v1/sandboxes", dependencies=[Depends(verify_api_key)])
159 | async def list_sandboxes(namespace: Optional[str] = None):
160 | """List all sandboxes."""
161 | core = K7Core()
162 | sandboxes = core.list_sandboxes(namespace)
163 | return success_response([sandbox.to_dict() for sandbox in sandboxes])
164 |
165 |
166 | @app.get("/api/v1/sandboxes/{name}", dependencies=[Depends(verify_api_key)])
167 | async def get_sandbox(name: str, namespace: str = "default"):
168 | """Get a single sandbox by name."""
169 | core = K7Core()
170 | items = core.list_sandboxes(namespace)
171 | for s in items:
172 | if s.name == name:
173 | return success_response(s.to_dict())
174 | raise HTTPException(status_code=404, detail=f"Sandbox {name} not found in namespace {namespace}")
175 |
176 |
177 | @app.delete("/api/v1/sandboxes/{name}", dependencies=[Depends(verify_api_key)])
178 | async def delete_sandbox(name: str, namespace: str = "default"):
179 | """Delete a sandbox."""
180 | core = K7Core()
181 | result = core.delete_sandbox(name, namespace)
182 |
183 | if result.success:
184 | return success_response({"message": result.message})
185 | else:
186 | raise HTTPException(status_code=400, detail=result.error)
187 |
188 |
189 | @app.delete("/api/v1/sandboxes", dependencies=[Depends(verify_api_key)])
190 | async def delete_all_sandboxes(namespace: str = "default"):
191 | """Delete all sandboxes in a namespace."""
192 | core = K7Core()
193 | result = core.delete_all_sandboxes(namespace)
194 |
195 | if result.success:
196 | return success_response({"message": result.message, "results": result.data})
197 | else:
198 | raise HTTPException(status_code=400, detail=result.error)
199 |
200 |
201 | @app.post("/api/v1/sandboxes/{name}/exec", dependencies=[Depends(verify_api_key)])
202 | async def exec_command(name: str, command_data: dict, namespace: str = "default"):
203 | """Execute a command in a sandbox."""
204 | command = command_data.get("command", "")
205 | if not command:
206 | raise HTTPException(status_code=400, detail="Command is required")
207 |
208 | core = K7Core()
209 | result = core.exec_command(name, command, namespace)
210 | return success_response(result.to_dict())
211 |
212 |
213 | @app.post("/api/v1/install", dependencies=[Depends(verify_api_key)])
214 | async def install_node(install_data: dict):
215 | """Install K7 on target hosts."""
216 | core = K7Core()
217 | result = core.install_node(
218 | install_data.get("playbook"),
219 | install_data.get("inventory"),
220 | install_data.get("verbose", False),
221 | )
222 |
223 | if result.success:
224 | return success_response({"message": result.message})
225 | else:
226 | raise HTTPException(status_code=400, detail=result.error)
227 |
228 |
229 | @app.get("/api/v1/sandboxes/metrics", dependencies=[Depends(verify_api_key)])
230 | async def get_sandbox_metrics(namespace: Optional[str] = None):
231 | """Get resource usage metrics for sandboxes."""
232 | core = K7Core()
233 | metrics = core.get_sandbox_metrics(namespace)
234 | return success_response(metrics)
235 |
--------------------------------------------------------------------------------
/src/k7/api/requirements.txt:
--------------------------------------------------------------------------------
1 | fastapi==0.104.1
2 | uvicorn[standard]==0.24.0
3 | kubernetes==28.1.0
4 | pydantic==2.5.0
5 | python-multipart==0.0.6
6 | requests==2.31.0
7 | typer==0.9.0
8 | rich==13.7.0
9 | pyyaml==6.0.1
10 | python-dotenv==1.0.0
--------------------------------------------------------------------------------
/src/k7/cli/Dockerfile.cli:
--------------------------------------------------------------------------------
1 | FROM --platform=linux/amd64 ubuntu:24.04
2 | RUN apt-get update && apt-get install -y python3 python3-pip python3-venv gcc patchelf
3 |
4 | WORKDIR /app
5 | RUN python3 -m venv /app/venv
6 | ENV PATH="/app/venv/bin:$PATH"
7 | RUN pip install --no-cache-dir nuitka typer kubernetes python-dotenv pyyaml rich
8 |
9 | # Copy source package into build context (src layout)
10 | COPY src/k7/ /app/k7/
11 |
12 | # Build the binary with deploy assets embedded
13 | RUN python3 -m nuitka \
14 | --standalone --onefile \
15 | --include-module=yaml \
16 | --include-module=rich \
17 | --include-module=typer \
18 | --include-module=kubernetes \
19 | --include-module=dotenv \
20 | --include-data-dir=k7=k7 \
21 | k7/cli/k7.py
--------------------------------------------------------------------------------
/src/k7/cli/build.sh:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | set -euo pipefail
4 |
5 | # Ensure we run from repo root
6 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
7 | REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
8 | cd "$REPO_ROOT"
9 |
10 | VERSION=$(grep -Po '__version__\s*=\s*"\K[^" ]+' src/k7/__init__.py || echo 0.0.0)
11 |
12 | if ! command -v docker >/dev/null 2>&1; then
13 | echo "Docker is required. Please install Docker."
14 | exit 1
15 | fi
16 |
17 | # Build CLI onefile image
18 | echo "Building K7 CLI onefile image..."
19 | docker build --platform linux/amd64 -t k7-cli-builder -f src/k7/cli/Dockerfile.cli .
20 |
21 | # Extract binary
22 | mkdir -p dist
23 | container_id=$(docker create --platform linux/amd64 k7-cli-builder)
24 | docker cp "$container_id":/app/k7.bin ./dist/k7 || docker cp "$container_id":/app/k7.cli.bin ./dist/k7 || true
25 | docker rm -v "$container_id" >/dev/null
26 |
27 | if [ ! -f ./dist/k7 ]; then
28 | # Nuitka default onefile name is module name with .bin; try to locate it
29 | echo "Attempting to locate built binary in image..."
30 | echo "Build did not produce expected output. Please check Dockerfile build stage."
31 | exit 1
32 | fi
33 | chmod +x ./dist/k7
34 |
35 | echo "Creating Debian package for version $VERSION..."
36 | PKG_DIR=dist/k7_${VERSION}_amd64
37 | mkdir -p "$PKG_DIR/DEBIAN" "$PKG_DIR/usr/local/bin"
38 | cat > "$PKG_DIR/DEBIAN/control" <<'EOF'
39 | Package: k7
40 | Version: __VERSION__
41 | Section: utils
42 | Priority: optional
43 | Architecture: amd64
44 | Maintainer: K7 Team
45 | Description: K7 CLI for sandbox management
46 | Provides the `k7` command with embedded installer playbook.
47 | EOF
48 | sed -i "s/__VERSION__/$VERSION/" "$PKG_DIR/DEBIAN/control"
49 | cp ./dist/k7 "$PKG_DIR/usr/local/bin/k7"
50 | chmod 0755 "$PKG_DIR/usr/local/bin/k7"
51 |
52 | dpkg-deb --build "$PKG_DIR"
53 |
54 | echo "Built Debian package at: ${PKG_DIR}.deb"
55 | echo "Next step: run 'make install' to install the CLI."
--------------------------------------------------------------------------------
/src/k7/cli/install.sh:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env bash
2 | set -euo pipefail
3 |
4 | SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
5 | REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
6 | cd "$REPO_ROOT"
7 |
8 | PKG=$(ls -1t dist/k7_*_amd64.deb 2>/dev/null | head -n1 || true)
9 | BIN="dist/k7"
10 |
11 | # Check if uninstall was requested
12 | if [[ "${1:-}" == "uninstall" ]]; then
13 | echo "Uninstalling k7..."
14 | if dpkg -l k7 >/dev/null 2>&1; then
15 | echo "Removing k7 package..."
16 | dpkg -r k7
17 | elif [ -f "/usr/local/bin/k7" ]; then
18 | echo "Removing k7 binary from /usr/local/bin..."
19 | rm -f /usr/local/bin/k7
20 | else
21 | echo "k7 not found (not installed or already removed)"
22 | fi
23 | hash -r
24 | echo "k7 uninstalled"
25 | exit 0
26 | fi
27 |
28 | # ... existing install code ...
29 | if [ -n "$PKG" ] && [ -f "$PKG" ]; then
30 | echo "Installing $PKG..."
31 | dpkg -i "$PKG" || { apt-get -y -f install && dpkg -i "$PKG"; }
32 | hash -r
33 | echo "Installed. Try: k7 --help"
34 | elif [ -f "$BIN" ]; then
35 | echo "No .deb found; installing binary to /usr/local/bin..."
36 | install -m 0755 "$BIN" /usr/local/bin/k7
37 | hash -r
38 | echo "Installed. Try: k7 --help"
39 | else
40 | echo "Nothing to install. Run src/k7/cli/build.sh first, or 'make install' from the root of the repo."
41 | exit 1
42 | fi
--------------------------------------------------------------------------------
/src/k7/core/__init__.py:
--------------------------------------------------------------------------------
1 | from .core import K7Core
2 | from .models import SandboxConfig, SandboxInfo, ExecResult
3 |
4 | __all__ = ["K7Core", "SandboxConfig", "SandboxInfo", "ExecResult"]
5 |
--------------------------------------------------------------------------------
/src/k7/core/models.py:
--------------------------------------------------------------------------------
1 | from typing import Optional, List, Dict, Any
2 | from dataclasses import dataclass, asdict, fields
3 | import yaml
4 |
5 |
6 | @dataclass
7 | class SandboxConfig:
8 | """Data model for sandbox configuration"""
9 |
10 | name: str
11 | image: str
12 | namespace: str = "default"
13 | env_file: Optional[str] = None
14 | egress_whitelist: Optional[List[str]] = None
15 | limits: Optional[Dict[str, str]] = None
16 | before_script: str = ""
17 | # Security toggles (default off) and capabilities configuration
18 | pod_non_root: bool = False
19 | container_non_root: bool = False
20 | cap_drop: Optional[List[str]] = None # default behavior handled in core: drop ALL
21 | cap_add: Optional[List[str]] = None
22 | # Note: ingress isolation is enforced by core with a hardcoded NetworkPolicy
23 |
24 | def __post_init__(self):
25 | if self.limits is None:
26 | self.limits = {}
27 |
28 | @classmethod
29 | def from_yaml(cls, yaml_path: str) -> "SandboxConfig":
30 | with open(yaml_path, "r") as f:
31 | data = yaml.safe_load(f)
32 | return cls(**data)
33 |
34 | @classmethod
35 | def from_dict(cls, data: dict) -> "SandboxConfig":
36 | # Be forward/backward compatible with API by ignoring unknown keys
37 | allowed = {f.name for f in fields(cls)}
38 | filtered = {k: v for k, v in (data or {}).items() if k in allowed}
39 | return cls(**filtered)
40 |
41 | def to_dict(self) -> dict:
42 | return asdict(self)
43 |
44 |
45 | @dataclass
46 | class SandboxInfo:
47 | name: str
48 | namespace: str
49 | status: str
50 | ready: str
51 | restarts: int
52 | age: str
53 | image: str
54 | error_message: str = ""
55 |
56 | def to_dict(self) -> dict:
57 | return asdict(self)
58 |
59 |
60 | @dataclass
61 | class ExecResult:
62 | exit_code: int
63 | stdout: str
64 | stderr: str
65 | duration_ms: int
66 |
67 | def to_dict(self) -> dict:
68 | return asdict(self)
69 |
70 |
71 | @dataclass
72 | class OperationResult:
73 | success: bool
74 | message: str = ""
75 | error: str = ""
76 | data: Any = None
77 |
78 | def to_dict(self) -> dict:
79 | return asdict(self)
80 |
--------------------------------------------------------------------------------
/src/k7/deploy/inventory.local.ini:
--------------------------------------------------------------------------------
1 | [k7_nodes]
2 | localhost ansible_connection=local ansible_user=root
3 |
--------------------------------------------------------------------------------
/src/k7/deploy/k7-install-node.yaml:
--------------------------------------------------------------------------------
1 |
2 | - name: Provision Bare Metal instance for K7
3 | hosts: k7_nodes
4 | become: yes
5 | vars:
6 | target_user: "{{ ansible_user }}"
7 | helm_version: "v3.15.2"
8 |
9 | tasks:
10 | - name: Gather facts (ensures ansible_distribution_release is available)
11 | setup:
12 |
13 | - name: Update apt cache and upgrade all packages
14 | ansible.builtin.apt:
15 | update_cache: yes
16 | upgrade: dist
17 | autoremove: yes
18 | tags: ['system_update']
19 |
20 | # ---- LVM utilities (needed for pvcreate/vgcreate/lvcreate) ----
21 | - name: Install LVM2
22 | ansible.builtin.apt:
23 | name: lvm2
24 | state: present
25 | tags: ['lvm']
26 |
27 | # Section: KVM Installation
28 | - name: Install required KVM and support utilities
29 | ansible.builtin.apt:
30 | name:
31 | - bridge-utils
32 | - cpu-checker
33 | - jq
34 | state: present
35 | tags: ['kvm']
36 |
37 | - name: Check if KVM acceleration can be used
38 | ansible.builtin.command: kvm-ok
39 | register: kvm_ok_result
40 | changed_when: false
41 | failed_when: "'KVM acceleration can be used' not in kvm_ok_result.stdout and 'INFO: /dev/kvm exists' not in kvm_ok_result.stdout"
42 | tags: ['kvm']
43 |
44 | - name: Ensure KVM modules (generic, Intel, AMD) are configured to load at boot
45 | ansible.builtin.lineinfile:
46 | path: /etc/modules-load.d/k7-kvm.conf
47 | line: "{{ item }}"
48 | create: yes
49 | mode: '0644'
50 | loop:
51 | - kvm
52 | - kvm_intel
53 | - kvm_amd
54 | - dm_thin_pool
55 | tags: ['kvm']
56 |
57 | - name: Load KVM + device-mapper thin-pool modules
58 | ansible.builtin.shell: |
59 | for mod in kvm kvm_intel kvm_amd dm_thin_pool; do
60 | modprobe "$mod" 2>/dev/null || true
61 | done
62 | changed_when: false
63 | tags: ['kvm']
64 |
65 | - name: Add target user {{ target_user }} to the KVM group
66 | ansible.builtin.user:
67 | name: "{{ target_user }}"
68 | groups: kvm
69 | append: yes
70 | tags: ['kvm']
71 |
72 | - name: Check /dev/kvm ownership
73 | stat:
74 | path: /dev/kvm
75 | register: kvm_dev
76 |
77 | - name: Fail if /dev/kvm is not owned by kvm group
78 | fail:
79 | msg: "/dev/kvm must be owned by group 'kvm'. Check system configuration."
80 | when:
81 | - kvm_dev.stat.exists
82 | - kvm_dev.stat.grp is defined
83 | - kvm_dev.stat.grp != 'kvm'
84 |
85 | # ---------------------------------------------------------------------------------------
86 | # Force iptables/ip6tables legacy backend (slaves follow automatically) (this is for k3s)
87 | # ---------------------------------------------------------------------------------------
88 | - name: Set iptables master alternative to legacy
89 | command: update-alternatives --set iptables /usr/sbin/iptables-legacy
90 | changed_when: "'link group' in result.stdout or result.rc == 0"
91 | register: result
92 | tags: ['iptables']
93 |
94 | - name: Set ip6tables master alternative to legacy
95 | command: update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy
96 | changed_when: "'link group' in result.stdout or result.rc == 0"
97 | register: result
98 | tags: ['iptables']
99 |
100 | - name: Ensure xt_mark module loads at boot and now
101 | lineinfile:
102 | path: /etc/modules-load.d/k7.conf
103 | line: xt_mark
104 | create: yes
105 | notify: Load xt_mark
106 | tags: ['iptables']
107 |
108 | - name: Load xt_mark module now
109 | command: modprobe xt_mark
110 | changed_when: false # no “changed” output on reruns
111 | tags: ['iptables']
112 |
113 |
114 | # ------------------------------------------------------------------
115 | # Ensure the devmapper stanza is absent before first K3s start
116 | # ------------------------------------------------------------------
117 | - name: Remove devmapper snapshotter block (if present) early
118 | blockinfile:
119 | path: /var/lib/rancher/k3s/agent/etc/containerd/config-v3.toml.tmpl
120 | marker: "# {mark} ANSIBLE MANAGED DEVMAPPER"
121 | state: absent
122 | create: yes
123 | tags: ['devmapper']
124 |
125 | # ------------------------------------------------------------------
126 | # Ensure no stale rendered config.toml forces devmapper on first boot
127 | # ------------------------------------------------------------------
128 | - name: Remove previously rendered containerd config
129 | file:
130 | path: /var/lib/rancher/k3s/agent/etc/containerd/config.toml
131 | state: absent
132 | tags: ['k3s']
133 |
134 | # ------------------------------------------------------------------
135 | # Minimal CNI so containerd’s CRI plugin can start on first boot
136 | # ------------------------------------------------------------------
137 | - name: Download CNI plugin tarball early
138 | get_url:
139 | url: https://github.com/containernetworking/plugins/releases/download/v1.3.0/cni-plugins-linux-amd64-v1.3.0.tgz
140 | dest: /tmp/cni-plugins.tgz
141 | mode: '0644'
142 | tags: ['cni']
143 |
144 | - name: Ensure /opt/cni/bin exists
145 | file:
146 | path: /opt/cni/bin
147 | state: directory
148 | mode: '0755'
149 | tags: ['cni']
150 |
151 | - name: Extract CNI plugins early
152 | unarchive:
153 | src: /tmp/cni-plugins.tgz
154 | dest: /opt/cni/bin
155 | remote_src: yes
156 | tags: ['cni']
157 |
158 | # ─── CNI bootstrap (single-file loopback) ─────────────────────────────
159 |
160 | - name: Wipe CNI conf dirs before first k3s start
161 | file:
162 | path: "{{ item }}"
163 | state: absent
164 | loop:
165 | - /etc/cni/net.d
166 | - /var/lib/rancher/k3s/agent/etc/cni/net.d # ← just in case
167 | tags: [cni]
168 |
169 | # Recreate the single dir that containerd will read
170 | - name: Re-create /etc/cni/net.d directory
171 | file:
172 | path: /etc/cni/net.d
173 | state: directory
174 | mode: '0755'
175 | tags: [cni]
176 |
177 | # Drop exactly one minimal loop-back config
178 | - name: Drop loop-back CNI config
179 | copy:
180 | dest: /etc/cni/net.d/99-loopback.conf
181 | mode: '0644'
182 | content: |
183 | {
184 | "cniVersion": "1.0.0",
185 | "name": "loopback",
186 | "type": "loopback"
187 | }
188 | tags: [cni]
189 |
190 | # NEW fix
191 | - name: Disable nftables FORWARD rules (they conflict with iptables)
192 | shell: |
193 | nft flush ruleset || true
194 | systemctl mask nftables || true
195 | tags: ['network']
196 |
197 | - name: Restart Docker to recreate iptables chains (after switching to legacy / flushing nft)
198 | ansible.builtin.systemd:
199 | name: docker
200 | state: restarted
201 | tags: ['docker','iptables']
202 |
203 | - name: Detect systemd-resolved resolv.conf
204 | stat:
205 | path: /run/systemd/resolve/resolv.conf
206 | register: resolved_resolv
207 | tags: ['dns']
208 |
209 | - name: Set k3s resolv.conf path
210 | set_fact:
211 | k3s_resolv_conf: "{{ resolved_resolv.stat.exists | ternary('/run/systemd/resolve/resolv.conf','/etc/resolv.conf') }}"
212 | tags: ['dns']
213 |
214 | - name: Persist iptables FORWARD rules for CNI traffic
215 | iptables:
216 | chain: FORWARD
217 | in_interface: cni0
218 | jump: ACCEPT
219 | action: insert
220 | rule_num: 1
221 | state: present
222 | tags: ['network']
223 |
224 | - name: Persist iptables FORWARD rules for return CNI traffic
225 | iptables:
226 | chain: FORWARD
227 | out_interface: cni0
228 | ctstate: ESTABLISHED,RELATED
229 | jump: ACCEPT
230 | action: insert
231 | rule_num: 1
232 | state: present
233 | tags: ['network']
234 |
235 |
236 | - name: Install K3s (but do NOT start it yet)
237 | shell: |
238 | curl -sfL https://get.k3s.io | INSTALL_K3S_SKIP_START=true K3S_RESOLV_CONF={{ k3s_resolv_conf }} INSTALL_K3S_EXEC='--disable=traefik --write-kubeconfig-mode 644 --cluster-cidr=10.42.0.0/16 --service-cidr=10.43.0.0/16' sh -
239 | args:
240 | creates: /usr/local/bin/k3s
241 | tags: ['k3s']
242 |
243 | # 📦 Section: Firecracker + Jailer Installation
244 | - name: Get latest Firecracker release tag
245 | uri:
246 | url: https://api.github.com/repos/firecracker-microvm/firecracker/releases/latest
247 | return_content: yes
248 | register: firecracker_release_info
249 | tags: ['firecracker']
250 |
251 | - name: Set Firecracker version
252 | set_fact:
253 | firecracker_version: "{{ firecracker_release_info.json.tag_name }}"
254 | tags: ['firecracker']
255 |
256 | - name: Download Firecracker & Jailer binaries
257 | get_url:
258 | url: "https://github.com/firecracker-microvm/firecracker/releases/download/{{ firecracker_version }}/firecracker-{{ firecracker_version }}-{{ ansible_architecture }}.tgz"
259 | dest: "/tmp/firecracker-{{ firecracker_version }}-{{ ansible_architecture }}.tgz"
260 | mode: '0644'
261 | tags: ['firecracker']
262 |
263 | - name: Create firecracker bin directory
264 | ansible.builtin.file:
265 | path: /opt/firecracker
266 | state: directory
267 | mode: '0755'
268 |
269 | - name: Extract Firecracker release
270 | ansible.builtin.unarchive:
271 | src: "/tmp/firecracker-{{ firecracker_version }}-{{ ansible_architecture }}.tgz"
272 | dest: "/opt/firecracker/"
273 | remote_src: yes
274 | extra_opts: [--strip-components=1]
275 | tags: ['firecracker']
276 |
277 | - name: Find firecracker binary
278 | find:
279 | paths: /opt/firecracker
280 | patterns: "firecracker*"
281 | recurse: no
282 | register: firecracker_binaries
283 |
284 | - name: Install `file` utility required for lookup('pipe', 'file ...')
285 | ansible.builtin.apt:
286 | name: file
287 | state: present
288 | tags: ['utils','firecracker']
289 |
290 | - name: Copy firecracker binary to final path (only if ELF)
291 | copy:
292 | src: "{{ item.path }}"
293 | dest: "/usr/local/bin/firecracker"
294 | remote_src: yes
295 | mode: '0755'
296 | loop: "{{ firecracker_binaries.files }}"
297 | when: >
298 | 'firecracker' in item.path and
299 | lookup('pipe', 'file ' ~ item.path) is search('ELF .* executable')
300 |
301 | - name: Find jailer binary
302 | find:
303 | paths: /opt/firecracker
304 | patterns: "jailer*"
305 | recurse: no
306 | register: jailer_binaries
307 |
308 | - name: Copy jailer binary to final path (only if ELF)
309 | copy:
310 | src: "{{ item.path }}"
311 | dest: "/usr/local/bin/jailer"
312 | remote_src: yes
313 | mode: '0755'
314 | loop: "{{ jailer_binaries.files }}"
315 | when: >
316 | 'jailer' in item.path and
317 | lookup('pipe', 'file ' ~ item.path) is search('ELF .* executable')
318 |
319 | - name: Remove bundled Firecracker & jailer
320 | file:
321 | path: "/opt/kata/bin/{{ item }}"
322 | state: absent
323 | loop: [firecracker, jailer]
324 | tags: ['kata','cleanup','firecracker','jailer']
325 |
326 | - name: Ensure jailer is set‑uid root
327 | file:
328 | path: /usr/local/bin/jailer
329 | mode: '4755'
330 | owner: root
331 | group: root
332 | tags: ['kata','firecracker','jailer']
333 |
334 | - name: Check Firecracker version
335 | command: /usr/local/bin/firecracker --version
336 | changed_when: false
337 | tags: ['firecracker']
338 |
339 | - name: Check Jailer version
340 | command: /usr/local/bin/jailer --version
341 | changed_when: false
342 | tags: ['firecracker','jailer']
343 |
344 | # Section: Install Kata Container
345 | - name: Download and install Kata Containers
346 | shell: |
347 | KATA_VERSION=$(curl -sSL https://api.github.com/repos/kata-containers/kata-containers/releases/latest | jq -r .tag_name)
348 | mkdir -p /opt/kata
349 |
350 | # Try .tar.zst first (newer format)
351 | TARBALL_ZST="kata-static-${KATA_VERSION}-amd64.tar.zst"
352 | URL_ZST="https://github.com/kata-containers/kata-containers/releases/download/${KATA_VERSION}/${TARBALL_ZST}"
353 |
354 | if curl -fsSL "$URL_ZST" -o "/tmp/$TARBALL_ZST" 2>/dev/null; then
355 | echo "Downloaded $TARBALL_ZST, extracting with zstd..."
356 | if command -v zstd >/dev/null 2>&1; then
357 | zstd -d "/tmp/$TARBALL_ZST" -o "/tmp/kata-static-${KATA_VERSION}-amd64.tar"
358 | tar -xvf "/tmp/kata-static-${KATA_VERSION}-amd64.tar" -C /
359 | else
360 | echo "Installing zstd..."
361 | apt-get update && apt-get install -y zstd
362 | zstd -d "/tmp/$TARBALL_ZST" -o "/tmp/kata-static-${KATA_VERSION}-amd64.tar"
363 | tar -xvf "/tmp/kata-static-${KATA_VERSION}-amd64.tar" -C /
364 | fi
365 | else
366 | # Fallback to .tar.xz (older format)
367 | echo "Trying fallback to .tar.xz format..."
368 | TARBALL_XZ="kata-static-${KATA_VERSION}-amd64.tar.xz"
369 | URL_XZ="https://github.com/kata-containers/kata-containers/releases/download/${KATA_VERSION}/${TARBALL_XZ}"
370 | curl -fsSL "$URL_XZ" -o "/tmp/$TARBALL_XZ"
371 | tar -xvf "/tmp/$TARBALL_XZ" -C /
372 | fi
373 | args:
374 | executable: /bin/bash
375 | tags: ['kata']
376 |
377 | - name: Point Kata to latest Firecracker / jailer
378 | replace:
379 | path: /opt/kata/share/defaults/kata-containers/configuration-fc.toml
380 | regexp: '^({{ item.key }}\s*=\s*).*'
381 | replace: '\1"/usr/local/bin/{{ item.name }}"'
382 | loop:
383 | - { key: 'path', name: 'firecracker' }
384 | - { key: 'jailer_path', name: 'jailer' }
385 | tags: ['kata','config','firecracker','jailer']
386 |
387 |
388 |
389 | - name: Set valid_hypervisor_paths
390 | lineinfile:
391 | path: /opt/kata/share/defaults/kata-containers/configuration-fc.toml
392 | regexp: '^valid_hypervisor_paths'
393 | line: 'valid_hypervisor_paths = ["/usr/local/bin/firecracker"]'
394 | tags: ['kata','config','firecracker']
395 |
396 | - name: Set valid_jailer_paths
397 | lineinfile:
398 | path: /opt/kata/share/defaults/kata-containers/configuration-fc.toml
399 | regexp: '^valid_jailer_paths'
400 | line: 'valid_jailer_paths = ["/usr/local/bin/jailer"]'
401 | tags: ['kata','config','jailer']
402 |
403 |
404 | - name: Create containerd shim symlink
405 | file:
406 | src: "/opt/kata/bin/containerd-shim-kata-v2"
407 | dest: "/usr/local/bin/containerd-shim-kata-v2"
408 | state: link
409 | tags: ['kata', 'containerd']
410 |
411 | - name: Ensure /opt/kata/share/kata-containers exists
412 | file:
413 | path: /opt/kata/share/kata-containers
414 | state: directory
415 | mode: '0755'
416 | tags: ['kata']
417 |
418 | # ------------------------------------------------------------------
419 | # Kata kernel (vmlinux.container)
420 | # ------------------------------------------------------------------
421 |
422 | - name: Check if vmlinux.container already exists (provided by kata-static)
423 | stat:
424 | path: /opt/kata/share/kata-containers/vmlinux.container
425 | register: kata_kernel
426 | tags: ['kata']
427 |
428 | - name: Get latest Kata Containers release metadata (only if kernel missing)
429 | uri:
430 | url: https://api.github.com/repos/kata-containers/kata-containers/releases/latest
431 | return_content: yes
432 | register: kata_release_info
433 | when: not kata_kernel.stat.exists
434 | tags: ['kata']
435 |
436 | - name: Set URL for vmlinux.container asset (only if kernel missing)
437 | set_fact:
438 | kata_kernel_url: >-
439 | {{
440 | kata_release_info.json.assets
441 | | selectattr('name', 'equalto', 'vmlinux.container')
442 | | map(attribute='browser_download_url')
443 | | first | default('')
444 | }}
445 | when: not kata_kernel.stat.exists
446 | tags: ['kata']
447 |
448 | - name: Fail when release has no vmlinux.container asset (only if kernel missing)
449 | fail:
450 | msg: >-
451 | The latest Kata release ({{ kata_release_info.json.tag_name }}) does not contain
452 | a `vmlinux.container` asset. Either switch to a release that ships the kernel,
453 | or build / copy your own kernel into /opt/kata/share/kata-containers/.
454 | when:
455 | - not kata_kernel.stat.exists
456 | - kata_kernel_url == ''
457 | tags: ['kata']
458 |
459 | - name: Download vmlinux.container (only if kernel missing and asset present)
460 | get_url:
461 | url: "{{ kata_kernel_url }}"
462 | dest: /opt/kata/share/kata-containers/vmlinux.container
463 | mode: '0644'
464 | when:
465 | - not kata_kernel.stat.exists
466 | - kata_kernel_url != ''
467 | tags: ['kata']
468 |
469 | # - name: Fail if GH_TOKEN is not set
470 | # fail:
471 | # msg: "GH_TOKEN environment variable must be set to access the private GitHub repo."
472 | # when: lookup('env', 'GH_TOKEN') == ""
473 | # tags: ['kata']
474 |
475 | # - name: Ensure GitHub CLI is installed
476 | # apt:
477 | # name: gh
478 | # state: present
479 | # update_cache: yes
480 | # tags: ['kata']
481 |
482 | # - name: Download kata-containers.img from GitHub Release
483 | # shell: |
484 | # gh release download v0.0.1 \
485 | # --repo Katakate/k7 \
486 | # --pattern "kata-containers.img" \
487 | # --dir /opt/kata/share/kata-containers \
488 | # --clobber
489 | # environment:
490 | # GH_TOKEN: "{{ lookup('env', 'GH_TOKEN') }}"
491 | # args:
492 | # creates: /opt/kata/share/kata-containers/kata-containers.img
493 | # tags: ['kata']
494 |
495 | - name: Ensure kernel path is configured in configuration-fc.toml
496 | lineinfile:
497 | path: /opt/kata/share/defaults/kata-containers/configuration-fc.toml
498 | regexp: '^#?\s*kernel\s*='
499 | line: 'kernel = "/opt/kata/share/kata-containers/vmlinux.container"'
500 | backrefs: yes
501 | tags: ['kata']
502 |
503 | - name: Ensure image path is configured in configuration-fc.toml
504 | lineinfile:
505 | path: /opt/kata/share/defaults/kata-containers/configuration-fc.toml
506 | regexp: '^#?\s*image\s*='
507 | line: 'image = "/opt/kata/share/kata-containers/kata-containers.img"'
508 | backrefs: yes
509 | tags: ['kata']
510 |
511 |
512 | - name: Ensure containerd template directory exists
513 | file:
514 | path: /var/lib/rancher/k3s/agent/etc/containerd
515 | state: directory
516 | mode: '0755'
517 | tags: ['kata', 'devmapper']
518 |
519 | # ──── BEGIN: spare-disk check ────
520 | - name: Detect root disk device
521 | set_fact:
522 | root_disk: "{{ (ansible_mounts | selectattr('mount', 'equalto', '/') | first).device
523 | | regex_replace('p?[0-9]+$','') }}"
524 | tags: ['lvm']
525 |
526 | - name: Find an empty secondary disk (skip loop, mapper, CD-ROM, zram, etc.)
527 | set_fact:
528 | kata_block: >-
529 | {{
530 | ansible_devices
531 | | dict2items
532 | | selectattr('value.partitions', 'equalto', {})
533 | | selectattr('value.removable', 'equalto', '0')
534 | | selectattr('value.size', 'defined')
535 | | rejectattr('value.size', 'equalto', '0 bytes')
536 | | selectattr('value.host', 'defined')
537 | | rejectattr('value.host', 'equalto', '')
538 | | rejectattr('key', 'match', root_disk | basename)
539 | | rejectattr('key', 'search', '^(dm-|mapper/|loop|sr|zram|zd)[0-9]+$')
540 | | map(attribute='key')
541 | | map('regex_replace', '^', '/dev/')
542 | | first | default('')
543 | }}
544 | tags: ['lvm']
545 |
546 |
547 |
548 | - name: Fail if no spare block device is available
549 | fail:
550 | msg: |
551 | No empty secondary disk found.
552 | K7 expects a dedicated data drive for the LVM thin-pool.
553 | Attach an extra NVMe/SSD (e.g. /dev/nvme2n1) and re-run the playbook.
554 | when: kata_block == ''
555 | tags: ['lvm']
556 | # ──── END spare-disk check ────
557 |
558 |
559 | - name: Ensure kata-vg exists
560 | command: vgdisplay kata-vg
561 | register: vgcheck
562 | failed_when: false
563 | changed_when: false
564 | tags: ['lvm']
565 |
566 | - name: pvcreate (with label)
567 | command: pvcreate -y --setphysicalvolumesize 100G --metadatasize 4M --dataalignment 1M {{ kata_block }}
568 | when: vgcheck.rc != 0
569 | tags: ['lvm']
570 |
571 | - name: Create VG if missing
572 | command: vgcreate kata-vg {{ kata_block }}
573 | when: vgcheck.rc != 0
574 | tags: ['lvm']
575 |
576 | - name: Add k7 tag to PV
577 | command: pvchange --addtag k7 {{ kata_block }}
578 | when: vgcheck.rc != 0
579 | tags: ['lvm']
580 |
581 | - name: Ensure thin pool LV exists
582 | command: >
583 | lvcreate -T kata-vg/thin-pool
584 | -l 95%FREE
585 | --poolmetadatasize 1G
586 | --chunksize 512K
587 | --yes
588 | args:
589 | creates: /dev/kata-vg/thin-pool
590 | tags: ['lvm']
591 |
592 | # – create the VG sub-folder so containerd can write its BoltDB
593 | - name: Create devmapper VG subdir
594 | file:
595 | path: /var/lib/rancher/k3s/agent/containerd/io.containerd.snapshotter.v1.devmapper/kata-vg
596 | #path: /var/lib/containerd/io.containerd.snapshotter.v1.devmapper/kata-vg
597 | state: directory
598 | mode: '0755'
599 | tags: ['devmapper', 'lvm']
600 |
601 | - name: Enable LVM thin-pool autoextend service
602 | copy:
603 | dest: /etc/lvm/profile/kata-thin.profile
604 | content: |
605 | activation {
606 | thin_pool_autoextend_threshold=80
607 | thin_pool_autoextend_percent=20
608 | }
609 | tags: ['lvm']
610 |
611 | - name: Attach profile to thin pool
612 | command: lvchange --metadataprofile kata-thin kata-vg/thin-pool
613 | tags: ['lvm']
614 |
615 |
616 | - name: Ensure skeleton containerd template exists (only once)
617 | copy:
618 | dest: /var/lib/rancher/k3s/agent/etc/containerd/config-v3.toml.tmpl
619 | content: |
620 | version = 3
621 | force: no # do NOT overwrite if it is already there
622 | mode: '0644'
623 | tags: ['containerd']
624 |
625 | - name: Write basic config-v3.toml.tmpl with devmapper only
626 | copy:
627 | dest: /var/lib/rancher/k3s/agent/etc/containerd/config-v3.toml.tmpl
628 | mode: "0644"
629 | owner: root
630 | content: |
631 | # version = 3
632 | {{ '{{' }} template "base" . {{ '}}' }}
633 |
634 | [plugins."io.containerd.snapshotter.v1.devmapper"]
635 | pool_name = "kata--vg-thin--pool"
636 | root_path = "/var/lib/rancher/k3s/agent/containerd/io.containerd.snapshotter.v1.devmapper"
637 | base_image_size = "10GB"
638 |
639 | - name: Add Kata runtime configuration to containerd template
640 | blockinfile:
641 | path: /var/lib/rancher/k3s/agent/etc/containerd/config-v3.toml.tmpl
642 | marker: "# {mark} ANSIBLE MANAGED KATA RUNTIME"
643 | block: |
644 | [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.kata]
645 | runtime_type = "io.containerd.kata.v2"
646 | privileged_without_host_devices = true
647 | snapshotter = "devmapper"
648 | [plugins."io.containerd.cri.v1.runtime".containerd.runtimes.kata.options]
649 | BinaryName = "/usr/local/bin/containerd-shim-kata-v2"
650 | ConfigPath = "/opt/kata/share/defaults/kata-containers/configuration-fc.toml"
651 | create: no
652 | insertafter: EOF
653 | tags: ['kata', 'containerd']
654 |
655 |
656 | # ── restart k3s non-blocking and wait for the API ─────────────────────────────
657 | - name: Restart K3s to apply devmapper changes (async)
658 | ansible.builtin.systemd:
659 | name: k3s
660 | state: restarted
661 | async: 300 # allow up to 5 min
662 | poll: 0 # fire-and-forget
663 | register: k3s_async
664 | tags: ['devmapper']
665 |
666 | - name: Wait for K3s containerd socket to appear
667 | wait_for:
668 | path: /run/k3s/containerd/containerd.sock
669 | state: present
670 | timeout: 60
671 | tags: ['kata']
672 |
673 | - name: Wait for kube-api /readyz
674 | command: k3s kubectl get --raw /readyz
675 | register: readyz
676 | retries: 30
677 | delay: 5
678 | until: readyz.rc == 0
679 |
680 | - name: Wait for node to be Ready and API stable
681 | shell: |
682 | for i in {1..30}; do
683 | if k3s kubectl get nodes --no-headers | grep -q 'Ready'; then
684 | echo "Node is Ready"
685 | # Test a more complex query to ensure stability
686 | if k3s kubectl get pods -n kube-system >/dev/null 2>&1; then
687 | exit 0
688 | fi
689 | fi
690 | echo "Waiting for node and API stability... ($i/30)"
691 | sleep 10
692 | done
693 | exit 1
694 | register: stability_check
695 | until: stability_check.rc == 0
696 | retries: 1 # The loop inside handles retries
697 | delay: 0
698 | tags: ['k3s']
699 |
700 |
701 | - name: Create RuntimeClass 'kata'
702 | ansible.builtin.shell: |
703 | cat <<'EOF' | k3s kubectl apply -f -
704 | apiVersion: node.k8s.io/v1
705 | kind: RuntimeClass
706 | metadata:
707 | name: kata
708 | handler: kata
709 | EOF
710 | args:
711 | executable: /bin/bash
712 | register: apply_kata
713 | retries: 12
714 | delay: 5
715 | until: "'created' in apply_kata.stdout or 'unchanged' in apply_kata.stdout"
716 | tags: ['kata','k3s']
717 |
718 |
719 | - name: Show K3s node status
720 | command: k3s kubectl get nodes -o wide
721 | register: k3s_nodes
722 | changed_when: false
723 | tags: ['k3s']
724 |
725 | - name: Debug K3s node status
726 | debug:
727 | msg: "{{ k3s_nodes.stdout_lines }}"
728 | tags: ['k3s']
729 |
730 | # - name: Download Helm installation script
731 | # get_url:
732 | # url: https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3
733 | # dest: /tmp/get_helm_3
734 | # mode: '0755'
735 | # tags: ['helm']
736 |
737 | # - name: Install Helm using script
738 | # command: /tmp/get_helm_3 --version {{ helm_version }}
739 | # args:
740 | # creates: /usr/local/bin/helm
741 | # environment:
742 | # USE_SUDO: "false"
743 | # HELM_INSTALL_DIR: /usr/local/bin
744 | # changed_when: "'Helm is already installed' not in helm_install_result.stdout"
745 | # register: helm_install_result
746 | # tags: ['helm']
747 |
748 | - name: Reminder about logging out and back in for group changes
749 | debug:
750 | msg: "IMPORTANT: User '{{ target_user }}' was added to 'docker' and/or 'kvm' groups. You (or the user) will need to log out and log back in on the server for these group changes to take full effect in their shell sessions."
751 | tags: ['info']
752 |
753 |
754 | handlers:
755 | - name: Load xt_mark
756 | ansible.builtin.command: modprobe xt_mark
757 |
758 |
--------------------------------------------------------------------------------
/src/katakate/__init__.py:
--------------------------------------------------------------------------------
1 | """
2 | Top-level K7 AI SDK package.
3 | """
4 |
5 | from .client import Client, AsyncClient, SandboxProxy
6 |
7 | __all__ = [
8 | "Client",
9 | "AsyncClient",
10 | "SandboxProxy",
11 | ]
12 |
13 | __version__ = "0.0.4-dev"
14 |
--------------------------------------------------------------------------------
/src/katakate/client.py:
--------------------------------------------------------------------------------
1 | import requests
2 | from typing import Optional, List
3 |
4 | try:
5 | import httpx # optional dependency for async client
6 | except Exception: # pragma: no cover
7 | httpx = None
8 |
9 |
10 | class SandboxProxy:
11 | """Proxy object for sandbox operations."""
12 |
13 | def __init__(self, name: str, namespace: str, client: "Client"):
14 | self.name = name
15 | self.namespace = namespace
16 | self._client = client
17 |
18 | def exec(self, code: str) -> dict:
19 | """Execute code in the sandbox."""
20 | return self._client._exec_command(self.name, code, self.namespace)
21 |
22 | def delete(self) -> dict:
23 | """Delete this sandbox."""
24 | return self._client.delete(self.name, self.namespace)
25 |
26 |
27 | class Client:
28 | """K7 Python SDK Client."""
29 |
30 | def __init__(self, endpoint: str, api_key: str, verify_ssl: bool = True):
31 | self.base_url = endpoint.rstrip("/")
32 | self.api_key = api_key
33 | self.session = requests.Session()
34 | self.session.headers.update({"X-API-Key": api_key})
35 | self.session.verify = verify_ssl
36 |
37 | def _unwrap(self, response) -> dict:
38 | data = response.json()
39 | if isinstance(data, dict) and "data" in data:
40 | return data["data"]
41 | return data
42 |
43 | def create(self, sandbox_config: dict) -> SandboxProxy:
44 | """Create a new sandbox and return a proxy object."""
45 | response = self.session.post(
46 | f"{self.base_url}/api/v1/sandboxes", json=sandbox_config
47 | )
48 | response.raise_for_status()
49 |
50 | name = sandbox_config.get("name")
51 | namespace = sandbox_config.get("namespace", "default")
52 |
53 | return SandboxProxy(name, namespace, self)
54 |
55 | def list(self, namespace: Optional[str] = None) -> List[dict]:
56 | """List all sandboxes."""
57 | params = {"namespace": namespace} if namespace else {}
58 | response = self.session.get(f"{self.base_url}/api/v1/sandboxes", params=params)
59 | response.raise_for_status()
60 | return self._unwrap(response)
61 |
62 | def delete(self, name: str, namespace: str = "default") -> dict:
63 | """Delete a sandbox."""
64 | response = self.session.delete(
65 | f"{self.base_url}/api/v1/sandboxes/{name}", params={"namespace": namespace}
66 | )
67 | response.raise_for_status()
68 | return self._unwrap(response)
69 |
70 | def delete_all(self, namespace: str = "default") -> dict:
71 | """Delete all sandboxes in a namespace."""
72 | response = self.session.delete(
73 | f"{self.base_url}/api/v1/sandboxes", params={"namespace": namespace}
74 | )
75 | response.raise_for_status()
76 | return self._unwrap(response)
77 |
78 | def install(
79 | self,
80 | playbook: Optional[str] = None,
81 | inventory: Optional[str] = None,
82 | verbose: bool = False,
83 | ) -> dict:
84 | """Install K7 on target hosts."""
85 | response = self.session.post(
86 | f"{self.base_url}/api/v1/install",
87 | json={"playbook": playbook, "inventory": inventory, "verbose": verbose},
88 | )
89 | response.raise_for_status()
90 | return self._unwrap(response)
91 |
92 | def get_metrics(self, namespace: Optional[str] = None) -> dict:
93 | """Get resource usage metrics for sandboxes."""
94 | params = {"namespace": namespace} if namespace else {}
95 | response = self.session.get(
96 | f"{self.base_url}/api/v1/sandboxes/metrics", params=params
97 | )
98 | response.raise_for_status()
99 | return self._unwrap(response)
100 |
101 | def _exec_command(self, name: str, command: str, namespace: str) -> dict:
102 | """Internal method to execute command in sandbox."""
103 | response = self.session.post(
104 | f"{self.base_url}/api/v1/sandboxes/{name}/exec",
105 | json={"command": command},
106 | params={"namespace": namespace},
107 | )
108 | response.raise_for_status()
109 | return self._unwrap(response)
110 |
111 |
112 | class AsyncClient:
113 | """K7 Python SDK Async Client."""
114 |
115 | def __init__(
116 | self,
117 | endpoint: str,
118 | api_key: str,
119 | verify_ssl: bool = True,
120 | timeout: float = 30.0,
121 | ):
122 | if httpx is None:
123 | raise RuntimeError(
124 | "httpx is required for AsyncClient. Install with `pip install httpx`."
125 | )
126 | self.base_url = endpoint.rstrip("/")
127 | self._client = httpx.AsyncClient(
128 | base_url=self.base_url,
129 | headers={"X-API-Key": api_key},
130 | verify=verify_ssl,
131 | timeout=timeout,
132 | )
133 |
134 | async def create(self, sandbox_config: dict) -> dict:
135 | r = await self._client.post("/api/v1/sandboxes", json=sandbox_config)
136 | r.raise_for_status()
137 | return r.json()
138 |
139 | async def list(self, namespace: Optional[str] = None) -> List[dict]:
140 | params = {"namespace": namespace} if namespace else {}
141 | r = await self._client.get("/api/v1/sandboxes", params=params)
142 | r.raise_for_status()
143 | data = r.json()
144 | if isinstance(data, dict) and "data" in data:
145 | return data["data"]
146 | return data
147 |
148 | async def delete(self, name: str, namespace: str = "default") -> dict:
149 | r = await self._client.delete(
150 | f"/api/v1/sandboxes/{name}", params={"namespace": namespace}
151 | )
152 | r.raise_for_status()
153 | data = r.json()
154 | if isinstance(data, dict) and "data" in data:
155 | return data["data"]
156 | return data
157 |
158 | async def delete_all(self, namespace: str = "default") -> dict:
159 | r = await self._client.delete(
160 | "/api/v1/sandboxes", params={"namespace": namespace}
161 | )
162 | r.raise_for_status()
163 | data = r.json()
164 | if isinstance(data, dict) and "data" in data:
165 | return data["data"]
166 | return data
167 |
168 | async def exec(self, name: str, command: str, namespace: str = "default") -> dict:
169 | r = await self._client.post(
170 | f"/api/v1/sandboxes/{name}/exec",
171 | json={"command": command},
172 | params={"namespace": namespace},
173 | )
174 | r.raise_for_status()
175 | data = r.json()
176 | if isinstance(data, dict) and "data" in data:
177 | return data["data"]
178 | return data
179 |
180 | async def get_metrics(self, namespace: Optional[str] = None) -> dict:
181 | params = {"namespace": namespace} if namespace else {}
182 | r = await self._client.get("/api/v1/sandboxes/metrics", params=params)
183 | r.raise_for_status()
184 | data = r.json()
185 | if isinstance(data, dict) and "data" in data:
186 | return data["data"]
187 | return data
188 |
189 | async def aclose(self):
190 | await self._client.aclose()
191 |
--------------------------------------------------------------------------------
/tutorials/k7_hetzner_node_setup.pdf:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Katakate/k7/f48ae38b9aeeec52e50aad8f157451b10e5ffc65/tutorials/k7_hetzner_node_setup.pdf
--------------------------------------------------------------------------------
/tutorials/langchain-react-agent/.env.example:
--------------------------------------------------------------------------------
1 | K7_ENDPOINT=https://your-k7-endpoint
2 | K7_API_KEY=your-api-key
3 | K7_SANDBOX_NAME=lc-agent
4 | K7_SANDBOX_IMAGE=alpine:latest
5 | K7_NAMESPACE=default
6 | OPENAI_API_KEY=sk-your-openai-key
7 | OPENAI_MODEL=gpt-4o-mini
--------------------------------------------------------------------------------
/tutorials/langchain-react-agent/README.md:
--------------------------------------------------------------------------------
1 | # LangChain ReAct Agent with K7 Sandbox Tool
2 |
3 | This tutorial shows a minimal LangChain ReAct-style agent equipped with a tool that executes shell commands inside a K7 sandbox.
4 |
5 | ## Prerequisites
6 | - K7 API deployed and reachable (use `k7 start-api` and check `k7 api-status` for the public URL)
7 | - API key generated: `k7 generate-api-key `
8 | - Python 3.10+
9 | - uv (recommended): https://docs.astral.sh/uv/
10 |
11 | ## Setup
12 | 0. Install uv (if not installed):
13 | ```
14 | curl -LsSf https://astral.sh/uv/install.sh | sh
15 | ```
16 |
17 | 1. Create a `.env` file in this directory with:
18 | ```
19 | K7_ENDPOINT=https://your-k7-endpoint
20 | K7_API_KEY=your-api-key
21 | K7_SANDBOX_NAME=lc-agent
22 | K7_SANDBOX_IMAGE=alpine:latest
23 | K7_NAMESPACE=default
24 | OPENAI_API_KEY=sk-your-openai-key
25 | OPENAI_MODEL=gpt-4o-mini
26 | ```
27 |
28 | 2. Create an isolated environment and install dependencies (using uv):
29 | ```
30 | # from this tutorial directory
31 | uv venv .venv-lc
32 | . .venv-lc/bin/activate
33 |
34 | # core deps for the tutorial
35 | uv pip install -r requirements.txt
36 |
37 | # install the local K7 SDK from the repo source
38 | # (two levels up from this tutorial dir)
39 | uv pip install -e ../..
40 |
41 | # or from the PyPI registry:
42 | uv pip install katakate
43 | ```
44 |
45 | ## Run
46 | ```
47 | python agent.py
48 | ```
49 |
50 | Ask the agent to perform simple shell actions, e.g., "List files in /". The agent will decide to use the sandbox tool and return the output.
51 |
52 | In parallel if you want you can shell into its sandbox:
53 | ```shell
54 | k7 shell lc-agent
55 | ```
56 | or replace `lc-agent` with the sandbox name you chose.
--------------------------------------------------------------------------------
/tutorials/langchain-react-agent/agent.py:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env python3
2 | import os
3 | import time
4 | from pathlib import Path
5 | from typing import Optional
6 |
7 | from dotenv import load_dotenv
8 |
9 | # LangChain
10 | from langchain.agents import initialize_agent, AgentType
11 | from langchain.memory import ConversationBufferMemory
12 | from langchain.tools import Tool
13 | from langchain_openai import ChatOpenAI
14 |
15 | # K7 SDK
16 | from katakate import Client, SandboxProxy
17 |
18 | load_dotenv(dotenv_path=Path(__file__).parent / ".env")
19 |
20 | K7_ENDPOINT = os.getenv("K7_ENDPOINT")
21 | K7_API_KEY = os.getenv("K7_API_KEY")
22 | OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
23 | SANDBOX_NAME = os.getenv("K7_SANDBOX_NAME", "lc-agent")
24 | SANDBOX_IMAGE = os.getenv("K7_SANDBOX_IMAGE", "alpine:latest")
25 | SANDBOX_NAMESPACE = os.getenv("K7_NAMESPACE", "default")
26 |
27 | if not K7_ENDPOINT or not K7_API_KEY:
28 | raise SystemExit("K7_ENDPOINT and K7_API_KEY must be set in .env")
29 | if not OPENAI_API_KEY:
30 | raise SystemExit("OPENAI_API_KEY must be set in .env for this LangChain example")
31 |
32 | k7 = Client(endpoint=K7_ENDPOINT, api_key=K7_API_KEY)
33 | _sb: Optional[SandboxProxy] = None
34 |
35 |
36 | def ensure_sandbox_ready(timeout_seconds: int = 60) -> SandboxProxy:
37 | try:
38 | # Prefer to create and get a proxy back
39 | sb = k7.create(
40 | {
41 | "name": SANDBOX_NAME,
42 | "image": SANDBOX_IMAGE,
43 | "namespace": SANDBOX_NAMESPACE,
44 | }
45 | )
46 | except Exception:
47 | # If already exists or creation fails, construct a proxy directly
48 | sb = SandboxProxy(SANDBOX_NAME, SANDBOX_NAMESPACE, k7)
49 |
50 | # Wait for pod to be Running
51 | deadline = time.time() + timeout_seconds
52 | while time.time() < deadline:
53 | items = k7.list(namespace=SANDBOX_NAMESPACE)
54 | for sb_info in items:
55 | if (
56 | sb_info.get("name") == SANDBOX_NAME
57 | and sb_info.get("status") == "Running"
58 | ):
59 | return sb
60 | time.sleep(2)
61 | raise RuntimeError("Sandbox did not become Running in time")
62 |
63 |
64 | def run_code_in_sandbox(code: str) -> str:
65 | global _sb
66 | if _sb is None:
67 | _sb = ensure_sandbox_ready()
68 | result = _sb.exec(code)
69 | stdout = result.get("stdout", "")
70 | stderr = result.get("stderr", "")
71 | if result.get("exit_code", 1) != 0:
72 | return f"[stderr]\n{stderr}\n[stdout]\n{stdout}"
73 | return stdout
74 |
75 |
76 | def main() -> None:
77 | tool = Tool(
78 | name="sandbox_exec",
79 | description="Execute a shell command inside an isolated K7 sandbox. Input should be a shell command string.",
80 | func=run_code_in_sandbox,
81 | )
82 |
83 | llm = ChatOpenAI(model=os.getenv("OPENAI_MODEL", "gpt-4o-mini"), temperature=0.0)
84 |
85 | memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True)
86 |
87 | agent = initialize_agent(
88 | tools=[tool],
89 | llm=llm,
90 | agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,
91 | memory=memory,
92 | verbose=True,
93 | handle_parsing_errors=True,
94 | )
95 |
96 | print("Ask me to run a command in a sandbox, e.g.: 'List files in /'\n")
97 | while True:
98 | try:
99 | user = input("You: ")
100 | except (EOFError, KeyboardInterrupt):
101 | break
102 | if not user.strip():
103 | continue
104 | resp = agent.invoke({"input": user})
105 | # resp can be dict with output
106 | print("Agent:", resp.get("output", str(resp)))
107 |
108 |
109 | if __name__ == "__main__":
110 | main()
111 |
--------------------------------------------------------------------------------
/tutorials/langchain-react-agent/requirements.txt:
--------------------------------------------------------------------------------
1 | python-dotenv>=1.0.0
2 | langchain>=0.2.0
3 | langchain-openai>=0.1.0
--------------------------------------------------------------------------------
/utils/README.md:
--------------------------------------------------------------------------------
1 | Please see https://docs.katakate.org/guides/utilities
--------------------------------------------------------------------------------
/utils/stress_test.sh:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | # High-density stress test - Testing CPU limit enforcement
4 | COUNT=50
5 | NAMESPACE="stress-test"
6 | CPU_LIMIT="300m" # 0.3 cores per sandbox = 15 total cores (testing limits!)
7 | MEM_LIMIT="2Gi" # 2GB per sandbox = 100GB total
8 | STRESS_MEM="1500M" # Stress 1.5GB memory
9 |
10 | # Cleanup function
11 | cleanup() {
12 | echo ""
13 | echo "🧹 Caught signal! Cleaning up stress test resources..."
14 | echo "Deleting all sandboxes in namespace '$NAMESPACE'..."
15 |
16 | # Use -y flag to skip confirmation
17 | k7 delete-all -n $NAMESPACE -y 2>/dev/null || echo "No sandboxes to delete"
18 |
19 | echo "Removing temporary config files..."
20 | rm -f k7-stress-*.yaml
21 |
22 | echo "Deleting namespace '$NAMESPACE'..."
23 | k3s kubectl delete namespace $NAMESPACE 2>/dev/null || echo "Namespace already deleted"
24 |
25 | echo "✅ Cleanup complete!"
26 | exit 0
27 | }
28 |
29 | # Set up signal handlers for cleanup
30 | trap cleanup SIGINT SIGTERM EXIT
31 |
32 | echo "=== K7 CPU Limit Enforcement Test ==="
33 | echo "Target: $COUNT sandboxes"
34 | echo "Resources per sandbox: CPU=$CPU_LIMIT (0.3 cores), Memory=$MEM_LIMIT"
35 | echo "Total planned usage: CPU=15 cores, Memory=100GB"
36 | echo "Hardware capacity: 20 cores, ~128GB RAM"
37 | echo ""
38 | echo "🎯 TESTING CPU LIMITS: Each pod will try to use 100% of 1 CPU core"
39 | echo " but should be limited to only 0.3 cores by Kubernetes!"
40 | echo ""
41 |
42 | # Create namespace
43 | echo "Creating namespace '$NAMESPACE'..."
44 | k3s kubectl create namespace $NAMESPACE 2>/dev/null || echo "Namespace already exists"
45 |
46 | echo "Creating $COUNT sandbox configurations..."
47 |
48 | for i in $(seq 1 $COUNT); do
49 | cat < k7-stress-$i.yaml
50 | name: stress-pod-$i
51 | image: alpine:latest
52 | before_script: |
53 | # Add random delay to spread out package installs (0-30 seconds)
54 | sleep $((RANDOM % 30))
55 | echo "=== Pod $i: Installing stress-ng ==="
56 | apk add --no-cache stress-ng htop
57 | echo "=== Pod $i: Starting CPU limit enforcement test ==="
58 | echo "Pod $i: Attempting to use 100% of 1 CPU core (should be limited to 0.3)"
59 | # Try to use 1 full CPU at 100% load, but kubernetes should limit us to 300m
60 | stress-ng --cpu 1 --cpu-load 100 --vm 1 --vm-bytes $STRESS_MEM --timeout 900s &
61 | echo "=== Pod $i: CPU stress test active - testing 300m limit ==="
62 | limits:
63 | cpu: "$CPU_LIMIT"
64 | memory: "$MEM_LIMIT"
65 | ephemeral-storage: "1Gi"
66 | EOF
67 | done
68 |
69 | echo "Launching $COUNT sandboxes in batches of 10..."
70 |
71 | # Launch in batches
72 | for batch in $(seq 0 3); do
73 | start=$((batch * 10 + 1))
74 | end=$((batch * 10 + 10))
75 |
76 | echo "Launching batch $((batch + 1)): sandboxes $start-$end"
77 |
78 | for i in $(seq $start $end); do
79 | if [ $i -le $COUNT ]; then
80 | echo " Creating stress-pod-$i (CPU limit: $CPU_LIMIT)..."
81 | k7 create -f k7-stress-$i.yaml --namespace $NAMESPACE &
82 | fi
83 | done
84 |
85 | wait
86 | echo "Batch $((batch + 1)) launched, waiting 30 seconds..."
87 | sleep 30
88 | done
89 |
90 | echo ""
91 | echo "=== CPU LIMIT ENFORCEMENT TEST LAUNCHED! ==="
92 | echo ""
93 | echo "Expected behavior:"
94 | echo " ✅ Each sandbox should show ~0.300 CPU usage (not 1.000)"
95 | echo " ✅ Total cluster CPU: ~15 cores out of 20 available"
96 | echo " ✅ Memory usage: ~1.5GB per sandbox"
97 | echo ""
98 | echo "This proves Kubernetes CPU limits are working!"
99 | echo ""
100 | echo "Monitor the CPU enforcement:"
101 | echo " k7 top -n $NAMESPACE"
102 | echo " watch 'k3s kubectl top pods -n $NAMESPACE --sort-by=cpu'"
103 | echo ""
104 | echo "Verify limits are enforced:"
105 | echo " k3s kubectl describe pod -n $NAMESPACE | grep -A5 'Limits:'"
106 | echo ""
107 | echo "Clean up when done:"
108 | echo " k7 delete-all -n $NAMESPACE -y"
109 | echo " rm k7-stress-*.yaml"
110 | echo " k3s kubectl delete namespace $NAMESPACE"
111 | echo ""
112 | echo "Or just press Ctrl+C - automatic cleanup is enabled! 🧹"
113 | echo ""
114 | echo "🧪 SCIENCE: stress-ng tries to use 100% CPU but gets throttled to 300m!"
115 |
--------------------------------------------------------------------------------
/utils/wipe-disk.sh:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env bash
2 | set -euo pipefail
3 |
4 | # wipe-disk.sh — aggressively and safely wipe a single block device
5 | # Usage: ./wipe-disk.sh /dev/sdX_or_nvmeXnY
6 | #
7 | # After you type YES, this will:
8 | # - Unmount anything on the device/partitions and disable swap
9 | # - Close dm-crypt mappings (best effort)
10 | # - Stop mdadm arrays using its partitions and zero md superblocks
11 | # - Deactivate LVM VGs using it, then wipe PV/FS signatures
12 | # - Zap partition tables and signatures
13 | # - Zero first/last regions and try blkdiscard (if supported)
14 |
15 | die() { echo "Error: $*" >&2; exit 1; }
16 | run() { echo "+ $*"; "$@"; }
17 |
18 | [[ $# -ge 1 ]] || { echo "Usage: $0 /dev/sdX_or_nvmeXnY"; exit 1; }
19 |
20 | DEVICE_RAW="$1"
21 | DEVICE="$(readlink -f "$DEVICE_RAW" || echo "$DEVICE_RAW")"
22 | [[ -b "$DEVICE" ]] || die "$DEVICE is not a block device"
23 |
24 | # Accept only whole-disk nodes (not partitions)
25 | # Use -d to show only the device itself (no children), -n to suppress header
26 | dtype="$(lsblk -dn -o TYPE "$DEVICE" 2>/dev/null || echo "")"
27 | case "$dtype" in
28 | disk|mpath) : ;; # ok
29 | *) die "You gave a partition node ($DEVICE). Please provide the WHOLE DISK (e.g., /dev/nvme0n1 or /dev/sda).";;
30 | esac
31 |
32 | echo "=============================="
33 | echo " YOU ARE ABOUT TO WIPE: $DEVICE"
34 | echo "=============================="
35 | echo "This will destroy ALL partitions, RAID/LVM/crypto metadata, and filesystems."
36 | read -r -p "Type YES to proceed: " confirm
37 | [[ "$confirm" == "YES" ]] || { echo "Aborted."; exit 0; }
38 |
39 | # Helper: enumerate child partitions of the device
40 | partitions() {
41 | # Prints /dev/* entries for child partitions (if any)
42 | lsblk -rno PATH "$DEVICE" | tail -n +2 || true
43 | }
44 |
45 | echo "[1/7] Unmounting and disabling swap on the target device..."
46 | # Unmount anything mounted from the device or any of its partitions
47 | while read -r src; do
48 | [[ -z "$src" ]] && continue
49 | # Unmount all mountpoints that have this source
50 | while read -r mnt; do
51 | [[ -n "$mnt" ]] && run umount -R "$mnt" || true
52 | done < <(findmnt -rno TARGET -S "$src" 2>/dev/null || true)
53 | done < <(printf "%s\n" "$DEVICE" $(partitions))
54 |
55 | # Disable any swap that points to the device/partitions
56 | if [[ -r /proc/swaps ]]; then
57 | while read -r swdev _; do
58 | for src in "$DEVICE" $(partitions); do
59 | if [[ "$swdev" == "$src" ]]; then run swapoff "$swdev" || true; fi
60 | done
61 | done < <(tail -n +2 /proc/swaps | awk '{print $1" "$2}')
62 | fi
63 |
64 | echo "[2/7] Closing dm-crypt (LUKS) mappings on top of this device (best effort)..."
65 | if command -v lsblk >/dev/null 2>&1; then
66 | # Find any device-mapper names that depend on our base device or its parts
67 | while read -r dmname dtype pk; do
68 | [[ "$dtype" != "crypt" ]] && continue
69 | # If this crypt mapper ultimately uses our device or its partitions, close it
70 | if lsblk -rno PKNAME "/dev/$dmname" 2>/dev/null | grep -Eq "$(basename "$DEVICE")(p[0-9]+)?"; then
71 | if command -v cryptsetup >/dev/null 2>&1; then
72 | run cryptsetup luksClose "$dmname" || true
73 | fi
74 | if command -v dmsetup >/dev/null 2>&1; then
75 | run dmsetup remove "/dev/$dmname" || true
76 | fi
77 | fi
78 | done < <(lsblk -rno NAME,TYPE,PKNAME | awk '{print $1" "$2" "$3}')
79 | fi
80 |
81 | echo "[3/7] Stopping mdraid arrays that include this disk..."
82 | if command -v mdadm >/dev/null 2>&1; then
83 | # Stop any /dev/md* that lists one of our partitions as a member
84 | for md in /dev/md/* /dev/md*; do
85 | [[ -e "$md" ]] || continue
86 | if mdadm --detail "$md" >/dev/null 2>&1; then
87 | if mdadm --detail "$md" 2>/dev/null | grep -qE "$(basename "$DEVICE")(p[0-9]+)?"; then
88 | run mdadm --stop "$md" || true
89 | fi
90 | fi
91 | done
92 | fi
93 |
94 | echo "[4/7] Deactivating LVM that sits on this disk (if any)..."
95 | if command -v pvs >/dev/null 2>&1 && command -v vgchange >/dev/null 2>&1; then
96 | # Find VGs that have PVs on our device or its partitions and deactivate them
97 | while read -r vg pv; do
98 | for src in "$DEVICE" $(partitions); do
99 | if [[ "$pv" == "$src" ]]; then
100 | run vgchange -an "$vg" || true
101 | fi
102 | done
103 | done < <(pvs --noheadings -o vg_name,pv_name 2>/dev/null | awk '{$1=$1;print}')
104 | fi
105 |
106 | echo "[5/7] Clearing md superblocks and LVM/FS signatures on partitions..."
107 | for p in $(partitions); do
108 | if command -v mdadm >/dev/null 2>&1; then
109 | run mdadm --zero-superblock "$p" || true
110 | fi
111 | if command -v wipefs >/dev/null 2>&1; then
112 | run wipefs -fa "$p" || true
113 | fi
114 | done
115 |
116 | # Let udev settle and drop partition caches before touching the whole disk
117 | command -v udevadm >/dev/null 2>&1 && run udevadm settle || true
118 | run blockdev --rereadpt "$DEVICE" || true
119 |
120 | echo "[6/7] Zapping partition tables and signatures on the whole disk..."
121 | if command -v wipefs >/dev/null 2>&1; then
122 | run wipefs -fa "$DEVICE" || true
123 | fi
124 |
125 | if command -v sgdisk >/dev/null 2>&1; then
126 | run sgdisk --zap-all "$DEVICE" || true
127 | else
128 | echo "sgdisk not found; zeroing first/last 1MiB as a fallback..."
129 | run dd if=/dev/zero of="$DEVICE" bs=1M count=1 conv=fsync || true
130 | if command -v blockdev >/dev/null 2>&1; then
131 | SECTORS=$(blockdev --getsz "$DEVICE")
132 | SEEK=$(( SECTORS / 2048 - 1 )) # 2048 sectors ≈ 1 MiB at 512-byte sectors
133 | (( SEEK > 0 )) && run dd if=/dev/zero of="$DEVICE" bs=1M seek="$SEEK" count=1 conv=fsync || true
134 | fi
135 | fi
136 |
137 | echo "[7/7] Overwriting start/end of the disk and attempting secure discard..."
138 | # Zero first 100MiB to clear lingering metadata quickly
139 | run dd if=/dev/zero of="$DEVICE" bs=1M count=100 status=progress conv=fsync || true
140 |
141 | # Zero last ~100MiB
142 | if command -v blockdev >/dev/null 2>&1; then
143 | SECTORS=$(blockdev --getsz "$DEVICE")
144 | SEEK_VAL=$(( SECTORS / 2048 - 100 ))
145 | if (( SEEK_VAL > 0 )); then
146 | run dd if=/dev/zero of="$DEVICE" bs=1M seek="$SEEK_VAL" count=100 status=progress conv=fsync || true
147 | fi
148 | fi
149 |
150 | # Discard entire device if supported (SSD/NVMe)
151 | if command -v blkdiscard >/dev/null 2>&1; then
152 | run blkdiscard "$DEVICE" || echo "(blkdiscard not supported or failed; non-fatal)"
153 | fi
154 |
155 | # Final reread to clear any lingering kernel views
156 | run blockdev --rereadpt "$DEVICE" || true
157 | command -v partprobe >/dev/null 2>&1 && run partprobe "$DEVICE" || true
158 |
159 | echo
160 | echo "DONE: $DEVICE should now be blank. Current view:"
161 | lsblk -o NAME,TYPE,SIZE,MOUNTPOINTS "$DEVICE" || true
162 |
--------------------------------------------------------------------------------