docs/desktop/extensions-sdk/guides/invoke-host-binaries.md

title	description	keywords
Invoke host binaries	Add invocations to host binaries from the frontend with the extension SDK.	Docker, extensions, sdk, build

In some cases, your extension needs to invoke some command from the host (the computer of your users). For example, you might want to invoke the CLI of your cloud provider to create a new resource, or the CLI of a tool your extension provides, or even a shell script that you want to run on the host. You could do that executing the CLI from a container with the extension SDK. But this CLI needs to access the host's filesystem, which isn't easy nor fast if it runs in a container. Host binaries allow exactly this: to invoke from the extension executables (as binaries, shell scripts) shipped as part of your extension and deployed to the host. As extensions can run on multiple platforms, this means that you need to ship the executables for all the platforms you want to support.

Note

Only executables shipped as part of the extension can be invoked with the SDK.

In this example, this CLI will be a simple Hello world script that must be invoked with a parameter and will return a string.

Add the executables to the extension

Create a bash script for macOS and Linux, in the file binaries/unix/hello.sh with the following content:

#!/bin/sh
echo "Hello, $1!"

Create a batch script for Windows in another file binaries/windows/hello.cmd with the following content:

@echo off
echo "Hello, %1!"

Then update the Dockerfile to copy the binaries folder into the extension's container filesystem and make the files executable.

# Copy the binaries into the right folder
COPY --chmod=0755 binaries/windows/hello.cmd /windows/hello.cmd
COPY --chmod=0755 binaries/unix/hello.sh /linux/hello.sh
COPY --chmod=0755 binaries/unix/hello.sh /darwin/hello.sh

Invoke the executable from the UI

In your extension, use the Docker Desktop Client object to invoke the shell script provided by the extension with the ddClient.extension.host.cli.exec() function. In this example, the binary returns a string as result, obtained by result?.stdout, as soon as the extension view is rendered.

• For React
• For Vue
• For Angular
• For Svelte

export function App() {
  const ddClient = createDockerDesktopClient();
  const [hello, setHello] = useState("");

  useEffect(() => {
    const run = async () => {
      let binary = "hello.sh";
      if (ddClient.host.platform === 'win32') {
        binary = "hello.cmd";
      }

      const result = await ddClient.extension.host?.cli.exec(binary, ["world"]);
      setHello(result?.stdout);

    };
    run();
  }, [ddClient]);
    
  return (
    <div>
      {hello}
    </div>
  );
}

Important We don't have an example for Vue yet. Fill out the form{: target="blank" rel="noopener" class=""} and let us know you'd like a sample with Vue. {: .important }

Important We don't have an example for Angular yet. Fill out the form{: target="blank" rel="noopener" class=""} and let us know you'd like a sample with Angular. {: .important }

Important We don't have an example for Svelte yet. Fill out the form{: target="blank" rel="noopener" class=""} and let us know you'd like a sample with Svelte. {: .important }

Configure the metadata file

The host binaries must be specified in the metadata.json so that Docker Desktop copies them on the host when installing the extension. Once the extension is uninstalled, the binaries that were copied will be removed as well.

{
  "vm": {
    ...
  },
  "ui": {
    ...
  },
  "host": {
    "binaries": [
      {
        "darwin": [
          {
            "path": "/darwin/hello.sh"
          }
        ],
        "linux": [
          {
            "path": "/linux/hello.sh"
          }
        ],
        "windows": [
          {
            "path": "/windows/hello.cmd"
          }
        ]
      }
    ]
  }
}

The path must reference the path of the binary inside the container.