README
¶
knot
Knot is a powerful tool to manage Cloud Development Environment within a Nomad cluster or local environments. It provides a seamless blend of a user-friendly web interface and a command line interface. This dual approach streamlines the deployment process and simplifies access to development environments, making management an effortless endeavor and eliminating the need for each developer to manage their own configurations.
Features
- Web-Based Management Interface: Provides an easy-to-use, browser-based interface for managing environments.
- Visual Studio Code Integration: Allows access to Visual Studio Code right from your browser.
- Code Server Integration: Offers access to Code Server right from your browser.
- Terminal Access: Offers in-browser terminal access for seamless command-line operations.
- Command-Line Tools: Simplifies container access with handy command-line tools.
- User & Permission Management: Effectively manage users and their permissions.
- Groups: Control which templates are available to users.
- Environment Templates: Customizable templates for creating consistent development environments.
- Integration with Nomad: Ensures seamless integration with Nomad for efficient cluster management.
- Local Containers: Run containers on the local machine using Docker or Podman.
- KVM Virtual Machines: Run spaces as full virtual machines on KVM-capable nodes, with bridged or NAT networking — see KVM Nodes.
- Quotas: Limit by resource usage and by number of spaces per user.
- Development URL Management: Automatically generated URLs for development spaces.
- Support for VNC: Support for web based VNC servers such as KasmVNC.
- Remote Servers Maximize performance by deploying environment close to developers but manage templates and users from anywhere, no single point failure.
- Custom Roles: Create custom roles to manage permissions.
- Sharing: Spaces can be shared with other users allowing SSH and terminal access.
- Logging: Syslog compatible interface allows logging and display within a window.
- Tunneling: Securely expose development environments to the internet when required.
- Local Services Securely connect to services on your local machine from within a space.
- API: Provides an API for integration with other systems.
KVM Nodes
KVM spaces run as full virtual machines on nodes with /dev/kvm and a reachable libvirt daemon, booted from cloud images with bridged (static IP) or NAT networking. Setup and configuration are documented at getknot.dev/docs/configuration/kvm, with the VM specification reference at getknot.dev/docs/templates/kvm-templates.
API Versioning
The API version is specified in the request header:
X-Knot-Api-Version: 2025-03-10
Any non-breaking changes are available in all versions of the API while breaking changes are only available in the latest version of the API.
Security
knot is designed to be used within trusted environments rather than on the open internet, that is it is expected to be run on a private network with developers connecting to the it via a VPN or similar technology.
For complex deployments over many different locations a mesh network may be appropriate.
When tunneling is enabled the tunnel port is separate from the web interface and the agent interface, it is expected that public traffic be directed to the tunnel interface only.
Time-based one-time passwords (TOTP) should be enabled if the web interface is exposed to the internet. The TOTP code works with Google Authenticator, Microsoft Authenticator, and other TOTP apps.
Documentation
Documentation and Getting Started
Icons
Icons are sourced from:
- https://heroicons.com/outline
- https://flowbite.com/icons/
- https://github.com/homarr-labs/dashboard-icons
- https://github.com/devicons/devicon
Legal
Disclaimer: All product names, trademarks, and registered trademarks are the property of their respective owners. Icons are used for identification purposes only and do not imply endorsement.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd/scriptlingserver
Package scriptlingserver implements the plugin the scriptling CLI loads to use knot libraries and scripts.
|
Package scriptlingserver implements the plugin the scriptling CLI loads to use knot libraries and scripts. |
|
restrict
Package command_restrict holds the commands that restrict a space and show its restrictions, shared by the knot command (knot space restrict) and the agent inside a space (knot restrict).
|
Package command_restrict holds the commands that restrict a space and show its restrictions, shared by the knot command (knot space restrict) and the agent inside a space (knot restrict). |
|
examples
|
|
|
plugins/demo-go/peer
command
Command demolib is the binary peer of the demo-go knot plugin — and, in the peer-manifest model, the WHOLE plugin: there is no companion main.py.
|
Command demolib is the binary peer of the demo-go knot plugin — and, in the peer-manifest model, the WHOLE plugin: there is no companion main.py. |
|
integration-tests
|
|
|
harness
Package harness boots real knot servers and spaces for black-box API integration tests.
|
Package harness boots real knot servers and spaces for black-box API integration tests. |
|
internal
|
|
|
agentapi/agentproxy
Package agentproxy provides self-contained TCP/TLS stream-to-local-port proxying.
|
Package agentproxy provides self-contained TCP/TLS stream-to-local-port proxying. |
|
agentpackages
Package agentpackages caches scriptling package zips (knot.zip, libs.zip) for the in-space agent service API.
|
Package agentpackages caches scriptling package zips (knot.zip, libs.zip) for the in-space agent service API. |
|
authratelimit
Package authratelimit implements failed-login blocking.
|
Package authratelimit implements failed-login blocking. |
|
backupfile
Package backupfile reads and writes the folder a backup is kept in:
|
Package backupfile reads and writes the folder a backup is kept in: |
|
desktop
Package desktop implements knot's desktop mode: bare `knot` runs the full server (identical to `knot server`) plus a system tray icon whose menu offers to open the web UI in the default browser and to quit.
|
Package desktop implements knot's desktop mode: bare `knot` runs the full server (identical to `knot server`) plus a system tray icon whose menu offers to open the web UI in the default browser and to quit. |
|
devicegrant
Package devicegrant holds the pending sign-ins of the OAuth 2.0 device authorization grant (RFC 8628), which `knot connect` uses: the client gets a device code it keeps and a short user code it shows, the user approves the user code in the web interface, and the client polls the token endpoint with the device code until it gets its API token.
|
Package devicegrant holds the pending sign-ins of the OAuth 2.0 device authorization grant (RFC 8628), which `knot connect` uses: the client gets a device code it keeps and a short user code it shows, the user approves the user code in the web interface, and the client polls the token endpoint with the device code until it gets its API token. |
|
filestore
Package filestore implements knot's replicated file storage: buckets owned by a user, shareable with users and groups, holding objects whose content is replicated to every server in the cluster.
|
Package filestore implements knot's replicated file storage: buckets owned by a user, shareable with users and groups, holding objects whose content is replicated to every server in the cluster. |
|
lmchatkit
Package lmchatkit adapts the github.com/paularlott/lmchatkit library to knot's per-user, MCP-backed chat architecture.
|
Package lmchatkit adapts the github.com/paularlott/lmchatkit library to knot's per-user, MCP-backed chat architecture. |
|
nfsserver
Package nfsserver serves knot's file storage over NFSv4.0 and NFSv3, so buckets can be mounted by the operating system (the macOS Finder or mount_nfs) and by Docker and Podman as volumes with the local driver's nfs type, without FUSE.
|
Package nfsserver serves knot's file storage over NFSv4.0 and NFSv3, so buckets can be mounted by the operating system (the macOS Finder or mount_nfs) and by Docker and Podman as volumes with the local driver's nfs type, without FUSE. |
|
passkey
Package passkey runs the WebAuthn registration and sign-in ceremonies on top of go-webauthn.
|
Package passkey runs the WebAuthn registration and sign-in ceremonies on top of go-webauthn. |
|
passkey/virtualauth
Package virtualauth is a software WebAuthn authenticator for tests: it produces "none" attestations and ES256 assertions exactly as the specification lays them out, so ceremonies can be driven end to end without a browser.
|
Package virtualauth is a software WebAuthn authenticator for tests: it produces "none" attestations and ES256 assertions exactly as the specification lays them out, so ceremonies can be driven end to end without a browser. |
|
plugins
Package plugins implements knot's plugin system: a plugin is a folder in the configured PluginsPath whose declarations — permissions, menus, pages, handlers, MCP tools, logos, icons — live statically in a [tool.knot] table.
|
Package plugins implements knot's plugin system: a plugin is a folder in the configured PluginsPath whose declarations — permissions, menus, pages, handlers, MCP tools, logos, icons — live statically in a [tool.knot] table. |
|
scriptling/pluginfetch
Package pluginfetch implements the knot plugin's fetcher: the source of truth for knot:// scheme sources served to the scriptling CLI.
|
Package pluginfetch implements the knot plugin's fetcher: the source of truth for knot:// scheme sources served to the scriptling CLI. |
|
specwizard
Package specwizard implements the conversion layer between knot's native template spec formats (local container YAML and Nomad HCL) and the unified representation the web wizard edits.
|
Package specwizard implements the conversion layer between knot's native template spec formats (local container YAML and Nomad HCL) and the unified representation the web wizard edits. |
|
startlog
Package startlog keeps a short, in-memory log of each space's most recent start: what the server did before the space's agent connected (preparing volumes, pulling the image, creating and starting the container) and why a start failed.
|
Package startlog keeps a short, in-memory log of each space's most recent start: what the server did before the space's agent connected (preparing volumes, pulling the image, creating and starting the container) and why a start failed. |
|
util/excludes
Package excludes matches paths against exclude patterns, for the commands that copy directory trees: knot space mirror and knot file sync.
|
Package excludes matches paths against exclude patterns, for the commands that copy directory trees: knot space mirror and knot file sync. |
|
scripts
|
|
|
genico
command
Assembles a multi-size .ico (32-bit BGRA DIB entries + zero AND masks) from input PNGs; sizes come from the PNG dimensions.
|
Assembles a multi-size .ico (32-bit BGRA DIB entries + zero AND masks) from input PNGs; sizes come from the PNG dimensions. |
|
getversion
command
|
|
|
homebrew-formula
command
|
|
|
iconlist
command
|
|
|
iconthin
command
iconthin thins the strokes of a monochrome icon without altering its geometry: it thresholds the alpha channel, erodes the resulting mask by a radius (repeated 3x3 min-filter, an approximation of a disk), then downsamples with area averaging for smooth antialiased edges.
|
iconthin thins the strokes of a monochrome icon without altering its geometry: it thresholds the alpha channel, erodes the resulting mask by a radius (repeated 3x3 min-filter, an approximation of a disk), then downsamples with area averaging for smooth antialiased edges. |
Click to show internal directories.
Click to hide internal directories.