Kryon for Dart #

Powerful terminal execution, everywhere.

Run operating-system commands, stream their output, and manage the processes behind them — with an API designed so the dangerous thing is the one you have to ask for by name.

This is the Dart SDK of Kryon. Zero runtime dependencies — it orchestrates dart:io and nothing else.

1.0.0. Command execution and process streaming are implemented and pass the cross-language conformance corpus on Linux, macOS and Windows. PTY, terminal emulation and remote transports are specified but not implemented.

Install #

dependencies:
  kryon: ^1.0.0

dart pub add kryon

Requires Dart 3.0 or newer.

Run something #

import 'dart:convert';
import 'package:kryon/kryon.dart';

final runtime = Runtime(const ExecutionOptions(
  encoding: utf8,
  timeout: Duration(seconds: 30),
));

final result = await runtime.execute('git', ['status', '--porcelain']);

print(result.stdoutText);
print('${result.exitCode} ${result.ok} ${result.duration}');

Talk to something #

final proc = await runtime.spawn('dart', ['run', 'worker.dart']);
try {
  proc.write('job-1\n');
  await proc.closeStdin();

  await for (final chunk in proc.output) {
    stdout.write(utf8.decode(chunk.data, allowMalformed: true));
  }

  final result = await proc.wait();
  print('exit ${result.exitCode}');
} finally {
  // Leaving without this leaks the child. Always close in a finally.
  await proc.close();
}

Two things worth knowing #

Arguments are never interpreted #

await runtime.execute('wc', ['-l', userInput]);          // safe, whatever userInput is
await runtime.executeShell('wc -l $userInput');          // command injection

execute passes an argument vector to the operating system. No shell is involved, so nothing in an argument can expand, glob, chain or substitute. Shell semantics live behind executeShell — a separate method name, not a runInShell: true flag, because a boolean among a dozen options is easy to set by accident and easy to miss in review.

Kryon is not a sandbox #

Timeouts and output caps manage resources. They do not contain a hostile program. Isolation is a container, a VM, or an unprivileged account. See the threat model.

API #

Runtime([ExecutionOptions defaults]) #

Holds default options; safe to share. Every call may override them with a third positional ExecutionOptions. env merges with the runtime's env; everything else is replaced, and a boolean set explicitly to false really does turn a default off.

ExecutionResult #

executable, arguments, exitCode, signal, stdout, stderr, duration, termination, pid, stdoutTruncated, stderrTruncated, plus ok, stdoutText, stderrText and checked().

termination is exited, signaled, timeout, cancelled or outputLimit. The Kryon-initiated reasons win over the kernel's account: a process killed for exceeding its timeout reports timeout, because that is what you need in order to decide whether to retry.

KryonProcess #

pid, running, exitCode, write(), closeStdin(), output, signal(), terminate(), kill(), wait(), close().

output is a single-subscription Stream<OutputChunk> with real backpressure: pause it and Kryon pauses the underlying pipes, so the child blocks instead of your heap growing.

Errors #

The rule: failing to start is an error, failing while running is a result.

CommandNotFoundException, PermissionDeniedException, ProcessStartFailedException and InvalidArgumentsException throw — no process ran. ProcessFailedException, ProcessTimeoutException, ProcessCancelledException and ResourceLimitExceededException throw only under check: true, and each carries the ExecutionResult it came from. All implement KryonException.

A naming note #

The output-stream enum is OutputStream, not Stream. A package that exports a type called Stream shadows dart:async's Stream for everyone who imports it, which is a hostile thing to do to your users. The specification fixes semantics, not spelling.

Platform notes #

iOS does not permit an application to spawn arbitrary child processes. That is a platform rule, not a missing feature; the correct architecture there is a remote transport to a server that does the executing.

Flutter #

This package is pure Dart and has no Flutter dependency. A kryon_flutter package for terminal rendering does not exist and will not be created until it has a clear purpose beyond existing.

Develop #

cd dart
dart pub get
dart analyze
dart test
dart run example/kryon_example.dart

Tests drive a small helper program rather than real system commands, so they behave the same on every platform and touch nothing outside a temporary directory.

License #

Apache-2.0. See LICENSE.

If Kryon saves you time, you can buy me a coffee.